PD-278 — Plan d'implémentation (v2)¶

Changelog v1 → v2 : 19 écarts corrigés (3 BLQ + 9 MAJ + 7 MIN). Ajout table attestation (BLQ-01), audit refus synchrone (BLQ-02), alignement enum DB 5 valeurs (BLQ-03), codes 503/404 (MAJ-01/02), capture 401 pre-controller (MAJ-03), rétention attestations 10 ans (MAJ-04), convention verrouillage cross-module (MAJ-05), validation H-06 phase 0 (MAJ-06), BYPASSRLS contractualisé (MAJ-07), compatibilité ESM/CJS (MAJ-08), code contracts alignés spec (MAJ-09), 7 corrections mineures (MIN-01→07).

1. Découpage en composants¶

Vue d'ensemble¶

Phases d'ordonnancement¶

Phase 0 — Validation préalable
  Validation H-06 : vérifier que geo_copy_count existe dans DocumentSecure entity
  et est maintenu par la couche stockage (PD-279). Si absent ou stub, 
  documenter le gap avec story destination avant de poursuivre.
  Vérification : entité, migration, tests existants sur geo_copy_count.

Phase 1 — Fondations (C1, C2, C3, C4, C5, C6, C7)
  Migration + enum + entity attestation + machine à états + config + DTOs + types audit/journal
  Parallélisable : C4/C5/C6/C7 sont indépendants entre eux.

Phase 2 — Core métier (C8, C9, C10, C11)
  Rate-limit guard + Service DIP + Controller + Exception filter
  Séquençage : C8 → C9 → C10/C11 (C10 et C11 parallélisables).

Phase 3 — Vérification formelle (C12)
  TLA+ alignment (indépendant du code applicatif).

Phase 4 — Tests (C13)
  Unitaires + intégration sur tous les composants.
  Framework : Jest + ts-jest (transformer TypeScript).

2. Flux techniques¶

2.1 Flux F1 — Communication AIP vers DIP (POST /api/v1/documents/disseminations)¶

Client → [JwtAuthGuard] → [AuthorizationGuard(PA,SA,auditor)]
       → [DisseminationRateLimitGuard (60/min + 1000/jour)]
       → [DisseminationAuditExceptionFilter]
       → DisseminationController.disseminate()
         → Validation DTO (ParseUUIDPipe, class-validator)
           - documents[]: UUID[], 1..100
           - motif_communication?: string, 0..1024
           - Rejet si champs serveur fournis (dissemination_package_id, timestamps)
         → DisseminationService.disseminate(dto, actorId)
           → QueryRunner.startTransaction()
             → SET LOCAL app.current_user_id = actorId  (RLS context)
             → SELECT FOR UPDATE ... ORDER BY id ASC  (verrouillage ordonné)
               Pour chaque document :
                 → Guard état : status = SEALED ? (sinon E-409-STATE)
                 → Guard copies : geo_copy_count >= MIN_COPIES ? (sinon E-422-GUARD-COPIES)
                 → Guard retention : retention_due = false ? (sinon E-409-RETENTION-DUE)
               Si un document échoue → ROLLBACK global (INV-278-11)
             → Génération dissemination_package_id (si multi: crypto.randomUUID(), si mono: NULL)
             → UPDATE status = DIP, disseminated_at = NOW(), disseminated_by = actorId,
                      dissemination_package_id, motif_communication
             → INSERT attestation dans vault_secure.dissemination_attestations (même tx)
             → INSERT outbox audit DOCUMENT_DISSEMINATED (même transaction)
           → QueryRunner.commitTransaction()
           → AuditLogService.logAsync(DOCUMENT_DISSEMINATED) (post-commit, non-bloquant)
         ← 201 Created + attestation response

2.2 Flux F2 — Retour DIP vers SEALED (POST /api/v1/documents/{id}/dissemination-return)¶

Client → [JwtAuthGuard] → [AuthorizationGuard(PA,SA,auditor,retention_service)]
       → [DisseminationAuditExceptionFilter]
       → DisseminationController.returnFromDissemination(documentId)
         → DisseminationService.returnFromDissemination(documentId, actorId)
           → QueryRunner.startTransaction()
             → SET LOCAL app.current_user_id = actorId  (RLS context)
             → SELECT FOR UPDATE WHERE id = documentId
               → Guard état : status = DIP ? (sinon E-409-STATE)
             → dissemination_returned_at = max(NOW(), disseminated_at) (INV-278-13)
             → UPDATE status = SEALED, dissemination_returned_at
             → INSERT outbox audit DOCUMENT_RETURNED (même transaction)
           → QueryRunner.commitTransaction()
           → AuditLogService.logAsync(DOCUMENT_RETURNED) (post-commit)
         ← 200 OK

2.3 Flux de refus sécurité (audit SYNCHRONE — spec §5.8)¶

Requête → Guard rejette (401/403/429/409-RETENTION-DUE)
       → DisseminationAuditExceptionFilter.catch()
         → QueryRunner dédié (transaction légère)
           → BEGIN
           → INSERT audit DOCUMENT_DISSEMINATION_DENIED (
               actor_id, document_id si résolu, reason_code, http_status
             )
           → COMMIT
         → Persistance GARANTIE avant retour de la réponse HTTP
       ← HTTP error response

Mécanisme de capture 401 pre-controller (MAJ-03) : Les guards JwtAuthGuard et AuthorizationGuard sont appliqués via @UseGuards() au niveau du controller. Dans NestJS, l'exception zone d'un controller inclut ses guards décorés — le @UseFilters(DisseminationAuditExceptionFilter) sur le controller capture donc les exceptions levées par ses guards. Aucun APP_GUARD global n'est nécessaire car les guards sont scopés au controller DIP. Si un 401 survient en amont d'un autre controller (hors scope DIP), il n'est pas audité par ce filter (cohérent avec le périmètre).

2.4 Flux anti-contournement retention (INV-278-14)¶

Retention Orchestrator détecte retention_due = true sur document DIP
  → Appel interne POST /api/v1/documents/{id}/dissemination-return
    (acteur = retention_service, rôle technique avec BYPASSRLS)
  → DIP → SEALED (audité DOCUMENT_RETURNED)
  → Puis rétention existante applique SEALED → EXPIRED

BYPASSRLS pour retention_service : Le rôle technique retention_service possède BYPASSRLS au niveau PostgreSQL (pattern REX PD-16). Cela lui permet d'effectuer la clôture DIP→SEALED cross-owner sans être bloqué par les politiques RLS. Ce privilège est strictement limité au rôle retention_service et audité systématiquement (DOCUMENT_RETURNED).

2.5 Diagrammes Mermaid¶

2.5.1 Graphe de dependances des composants¶

graph TD
    C1["C1 — Migration DDL"]
    C2["C2 — Extension entities TypeScript"]
    C3["C3 — Extension machine a etats"]
    C4["C4 — Configuration DIP"]
    C5["C5 — DTOs et codes d'erreur"]
    C6["C6 — Extension types audit"]
    C7["C7 — Extension types journal"]
    C8["C8 — Rate-limit guard DIP"]
    C9["C9 — Service DIP (core metier)"]
    C10["C10 — Controller DIP"]
    C11["C11 — Exception filter audit refus"]
    C12["C12 — Modele formel TLA+"]
    C13["C13 — Tests"]

    C2 --> C1
    C3 --> C2
    C8 --> C4
    C8 --> C6
    C9 --> C2
    C9 --> C3
    C9 --> C4
    C9 --> C5
    C9 --> C6
    C9 --> C7
    C10 --> C5
    C10 --> C8
    C10 --> C9
    C11 --> C6
    C13 --> C1
    C13 --> C2
    C13 --> C3
    C13 --> C4
    C13 --> C5
    C13 --> C6
    C13 --> C7
    C13 --> C8
    C13 --> C9
    C13 --> C10
    C13 --> C11
    C13 --> C12

    subgraph "Phase 1 — Fondations"
        C1
        C2
        C3
        C4
        C5
        C6
        C7
    end

    subgraph "Phase 2 — Core metier"
        C8
        C9
        C10
        C11
    end

    subgraph "Phase 3 — Verification formelle"
        C12
    end

    subgraph "Phase 4 — Tests"
        C13
    end

2.5.2 Diagramme de sequence — Flux F1 (SEALED vers DIP)¶

sequenceDiagram
    participant Client
    participant JwtAuthGuard
    participant AuthorizationGuard
    participant RateLimitGuard as C8 DisseminationRateLimitGuard
    participant AuditFilter as C11 DisseminationAuditExceptionFilter
    participant Controller as C10 DisseminationController
    participant Service as C9 DisseminationService
    participant StateMachine as C3 DocumentStateMachineService
    participant DB as PostgreSQL (vault_secure)
    participant Redis
    participant AuditLog as AuditLogService

    Client->>JwtAuthGuard: POST /api/v1/documents/disseminations
    JwtAuthGuard->>AuthorizationGuard: Token valide
    AuthorizationGuard->>RateLimitGuard: Role autorise (PA/SA/auditor)
    RateLimitGuard->>Redis: INCR dip:rate:{actorId}
    Redis-->>RateLimitGuard: count <= 60/min, quota <= 1000/jour
    RateLimitGuard->>Controller: Requete autorisee
    Controller->>Controller: Validation DTO (ParseUUIDPipe, class-validator)
    Controller->>Service: disseminate(dto, actorId)

    Service->>DB: BEGIN TRANSACTION
    Service->>DB: SET LOCAL app.current_user_id = actorId (RLS)
    Service->>DB: SELECT FOR UPDATE ... ORDER BY id ASC
    DB-->>Service: Documents verrouilles

    loop Pour chaque document
        Service->>StateMachine: Garde etat = SEALED ?
        Service->>Service: Garde geo_copy_count >= MIN_COPIES ?
        Service->>Service: Garde retention_due = false ?
    end

    Service->>DB: UPDATE status = DIP, disseminated_at, disseminated_by, package_id, motif
    Service->>DB: INSERT INTO dissemination_attestations (meme tx)
    Service->>DB: INSERT outbox audit DOCUMENT_DISSEMINATED (meme tx)
    Service->>DB: COMMIT

    Service->>AuditLog: logAsync(DOCUMENT_DISSEMINATED) (post-commit)
    Service-->>Controller: Attestation response
    Controller-->>Client: 201 Created + attestation

2.5.3 Diagramme de sequence — Flux F2 (DIP vers SEALED)¶

sequenceDiagram
    participant Client
    participant JwtAuthGuard
    participant AuthorizationGuard
    participant AuditFilter as C11 DisseminationAuditExceptionFilter
    participant Controller as C10 DisseminationController
    participant Service as C9 DisseminationService
    participant StateMachine as C3 DocumentStateMachineService
    participant DB as PostgreSQL (vault_secure)
    participant AuditLog as AuditLogService

    Client->>JwtAuthGuard: POST /api/v1/documents/{id}/dissemination-return
    JwtAuthGuard->>AuthorizationGuard: Token valide
    AuthorizationGuard->>Controller: Role autorise (PA/SA/auditor/retention_service)
    Controller->>Service: returnFromDissemination(documentId, actorId)

    Service->>DB: BEGIN TRANSACTION
    Service->>DB: SET LOCAL app.current_user_id = actorId (RLS)
    Service->>DB: SELECT FOR UPDATE WHERE id = documentId
    DB-->>Service: Document verrouille

    Service->>StateMachine: Garde etat = DIP ?
    Service->>DB: UPDATE status = SEALED, returned_at = GREATEST(NOW(), disseminated_at)
    Service->>DB: INSERT outbox audit DOCUMENT_RETURNED (meme tx)
    Service->>DB: COMMIT

    Service->>AuditLog: logAsync(DOCUMENT_RETURNED) (post-commit)
    Service-->>Controller: OK
    Controller-->>Client: 200 OK

2.5.4 Diagramme de sequence — Flux refus securite (audit synchrone)¶

sequenceDiagram
    participant Client
    participant Guard as JwtAuthGuard / AuthorizationGuard / RateLimitGuard
    participant AuditFilter as C11 DisseminationAuditExceptionFilter
    participant DB as PostgreSQL (vault_secure)

    Client->>Guard: Requete DIP
    Guard--xAuditFilter: Exception (401/403/429/409-RETENTION-DUE)

    AuditFilter->>DB: BEGIN (QueryRunner dedie)
    AuditFilter->>DB: INSERT audit DOCUMENT_DISSEMINATION_DENIED (actor, reason, http_status)
    AuditFilter->>DB: COMMIT
    Note over AuditFilter,DB: Persistance GARANTIE avant reponse HTTP

    AuditFilter-->>Client: HTTP error response (401/403/429/409)

3. Mapping invariants → mécanismes¶

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

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

5.1 Tests nominaux¶

5.2 Tests d'erreur¶

5.3 Tests d'invariants¶

5.4 Tests non-régression¶

5.5 Tests négatifs/adversariaux¶

5.6 Tests formels¶

6. Gestion des erreurs¶

Format réponse erreur (pattern PD-279) :

{
  "error_code": "E-409-RETENTION-DUE",
  "message": "Document blocked by retention policy",
  "details": { "document_id": "...", "retention_due": true }
}

7. Impacts sécurité¶

8. Hypothèses techniques¶

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

10. Hors périmètre¶

11. Mécanismes cross-module¶

12. Périmètre de test¶

Framework de test : Jest + ts-jest (transformer TypeScript). Configuration Jest existante dans jest.config.ts du projet backend.

Couverture minimale attendue : 80% sur le périmètre in scope (C1–C12). Tous les TC-NOM, TC-ERR, TC-INV, TC-NR, TC-NEG et TC-FML répertoriés ci-dessus sont in scope.

Matrice de couverture : TC-NOM-01 à TC-NOM-07, TC-ERR-01 à TC-ERR-14, TC-INV-01 à TC-INV-13, TC-NR-01 à TC-NR-06, TC-NEG-01 à TC-NEG-07, TC-FML-01 à TC-FML-02 = 49 tests contractuels.

13. Détails techniques par composant¶

C1 — Migration DDL¶

Fichier : src/database/migrations/1741400000000-PD278-AddDipState.ts

Séquence DDL : 1. ALTER TYPE vault_secure.document_status ADD VALUE IF NOT EXISTS 'DIP' — hors transaction (contrainte PostgreSQL) 2. ALTER TABLE vault_secure.documents ADD COLUMN IF NOT EXISTS disseminated_at TIMESTAMPTZ NULL 3. ALTER TABLE vault_secure.documents ADD COLUMN IF NOT EXISTS disseminated_by UUID NULL 4. ALTER TABLE vault_secure.documents ADD COLUMN IF NOT EXISTS dissemination_returned_at TIMESTAMPTZ NULL 5. ALTER TABLE vault_secure.documents ADD COLUMN IF NOT EXISTS dissemination_package_id UUID NULL 6. ALTER TABLE vault_secure.documents ADD COLUMN IF NOT EXISTS motif_communication VARCHAR(1024) NULL 7. ALTER TABLE vault_secure.documents ADD COLUMN IF NOT EXISTS retention_due BOOLEAN NOT NULL DEFAULT false 8. ALTER TABLE ... ADD CONSTRAINT chk_dip_temporal_order CHECK (dissemination_returned_at IS NULL OR disseminated_at IS NULL OR dissemination_returned_at >= disseminated_at) — INV-278-13 9. Trigger WORM motif_communication :

CREATE OR REPLACE FUNCTION vault_secure.trg_motif_communication_immutable()
RETURNS TRIGGER AS $$ BEGIN
  IF OLD.motif_communication IS NOT NULL AND NEW.motif_communication IS DISTINCT FROM OLD.motif_communication THEN
    RAISE EXCEPTION 'motif_communication is immutable after creation';
  END IF;
  RETURN NEW;
END; $$ LANGUAGE plpgsql;
CREATE TRIGGER trg_motif_communication_worm
  BEFORE UPDATE ON vault_secure.documents
  FOR EACH ROW EXECUTE FUNCTION vault_secure.trg_motif_communication_immutable();

CREATE TABLE IF NOT EXISTS vault_secure.dissemination_attestations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  attestation_id UUID NOT NULL UNIQUE,
  request_id UUID NOT NULL,
  document_ids UUID[] NOT NULL,
  actor_id UUID NOT NULL,
  issued_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  motif_communication VARCHAR(1024),
  dissemination_package_id UUID,
  hash_evidence TEXT NOT NULL,
  signature_ref TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Si partitioning natif :
CREATE TABLE vault_secure.dissemination_attestations (
  ...
) PARTITION BY RANGE (issued_at);

CREATE TABLE vault_secure.dissemination_attestations_2026
  PARTITION OF vault_secure.dissemination_attestations
  FOR VALUES FROM ('2026-01-01') TO ('2027-01-01');

Down migration : Vérifier COUNT(*) WHERE status = 'DIP' > 0 → exception si documents DIP actifs. Sinon : DROP table dissemination_attestations, DROP colonnes, DROP trigger, DROP index. Ne pas retirer la valeur enum (PostgreSQL ne supporte pas DROP VALUE).

C2 — Extension entities TypeScript¶

Fichiers : - src/modules/documents/entities/document-secure.entity.ts — extension enum + colonnes - src/modules/documents/entities/dissemination-attestation.entity.ts — nouvelle entity (BLQ-01)

Entity DisseminationAttestation :

@Entity('dissemination_attestations', { schema: 'vault_secure' })
export class DisseminationAttestation {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ type: 'uuid', unique: true })
  attestation_id: string;

  @Column({ type: 'uuid' })
  request_id: string;

  @Column({ type: 'uuid', array: true })
  document_ids: string[];

  @Column({ type: 'uuid' })
  actor_id: string;

  @Column({ type: 'timestamptz', default: () => 'NOW()' })
  issued_at: Date;

  @Column({ type: 'varchar', length: 1024, nullable: true })
  motif_communication: string | null;

  @Column({ type: 'uuid', nullable: true })
  dissemination_package_id: string | null;

  @Column({ type: 'text' })
  hash_evidence: string;

  @Column({ type: 'text', nullable: true })
  signature_ref: string | null;

  @CreateDateColumn({ type: 'timestamptz' })
  created_at: Date;
}

C4 — Configuration DIP¶

Fichier : src/modules/documents/config/dissemination.config.ts

registerAs('dissemination', () => ({
  minCopies: parseInt(process.env.DIP_MIN_COPIES ?? '2'),
  maxPackageSize: parseInt(process.env.DIP_MAX_PACKAGE_SIZE ?? '100'),
  slaTargetSealedToDipMs: parseInt(process.env.SLA_TARGET_SEALED_TO_DIP_MS ?? '2000'),
  slaTargetDipToSealedMs: parseInt(process.env.SLA_TARGET_DIP_TO_SEALED_MS ?? '1500'),
  slaHardTimeoutMs: parseInt(process.env.SLA_HARD_TIMEOUT_MS ?? '5000'),
  rateLimitPerMinute: parseInt(process.env.DIP_RATE_LIMIT_PER_MIN ?? '60'),
  quotaPerDay: parseInt(process.env.DIP_QUOTA_PER_DAY ?? '1000'),
}))

Validation Joi avec min/max pour chaque borne (pattern restitution.config.ts).

C8 — Rate-limit guard DIP¶

Fichier : src/modules/documents/guards/dissemination-rate-limit.guard.ts

Pattern : LegalRateLimitGuard (Redis INCR + EXPIRE).

• Clé rate-limit : dip:rate:{actorId} — TTL 60s
• Clé quota journalier : dip:quota:{actorId}:{YYYY-MM-DD} — TTL 86400s
• Si Redis indisponible → fail-closed 503 E-503-REDIS (pas de bypass)
• Sur rejet 429 → audit DOCUMENT_DISSEMINATION_DENIED synchrone via QueryRunner dédié dans le filter C11

C9 — Service DIP (core métier)¶

Fichier : src/modules/documents/services/dissemination.service.ts

Méthode disseminate(dto, actorId) : 1. Validation cardinalité (1..maxPackageSize) 2. queryRunner = dataSource.createQueryRunner() 3. queryRunner.startTransaction() 4. SET LOCAL app.current_user_id = actorId 5. SELECT * FROM vault_secure.documents WHERE id IN ($ids) ORDER BY id ASC FOR UPDATE — verrouillage ordonné ; commentaire // LOCK-ORDER: document_id ASC (§5.9) 6. Vérification : tous trouvés ? (sinon E-404-NOT-FOUND si inexistant, E-403-RLS si RLS filtré) 7. Pour chaque document : - état = SEALED ? (sinon E-409-STATE) - geo_copy_count >= minCopies ? (sinon E-422-GUARD-COPIES) - retention_due = false ? (sinon E-409-RETENTION-DUE) - Si un échoue → ROLLBACK global (INV-278-11) 8. package_id = documents.length > 1 ? randomUUID() : null 9. UPDATE : status=DIP, disseminated_at=NOW(), disseminated_by=actorId, package_id, motif 10. INSERT attestation dans vault_secure.dissemination_attestations (même tx) 11. INSERT outbox audit DOCUMENT_DISSEMINATED (même tx) 12. queryRunner.commitTransaction() 13. AuditLogService.logAsync(DOCUMENT_DISSEMINATED, ...) (post-commit, publication async)

Méthode returnFromDissemination(documentId, actorId) : 1. queryRunner.startTransaction() 2. SET LOCAL app.current_user_id = actorId 3. SELECT ... WHERE id = $id FOR UPDATE ; commentaire // LOCK-ORDER: document_id ASC (§5.9) 4. Vérification trouvé (sinon E-404-NOT-FOUND / E-403-RLS) 5. état = DIP ? (sinon E-409-STATE) 6. UPDATE status=SEALED, dissemination_returned_at = GREATEST(NOW(), disseminated_at) 7. INSERT outbox audit DOCUMENT_RETURNED (même tx) 8. queryRunner.commitTransaction() 9. AuditLogService.logAsync(DOCUMENT_RETURNED, ...) (post-commit)

C11 — Exception filter audit refus (SYNCHRONE — spec §5.8)¶

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

Pattern : DepositAuditExceptionFilter (PD-60), adapté pour persistance synchrone (BLQ-02).

@Catch(UnauthorizedException, ForbiddenException, HttpException)
export class DisseminationAuditExceptionFilter implements ExceptionFilter {
  constructor(
    private readonly dataSource: DataSource,
    private readonly auditLogService: AuditLogService,
  ) {}

  async catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const request = ctx.getRequest();
    const status = exception.getStatus();

    if ([401, 403, 429].includes(status) || 
        (status === 409 && exception.getResponse()?.['error_code'] === 'E-409-RETENTION-DUE')) {
      // Persistance SYNCHRONE via QueryRunner dédié (spec §5.8)
      const queryRunner = this.dataSource.createQueryRunner();
      try {
        await queryRunner.startTransaction();
        await queryRunner.query(
          `INSERT INTO vault_secure.audit_log (action_type, actor_id, metadata, created_at)
           VALUES ($1, $2, $3, NOW())`,
          [
            AuditActionType.DOCUMENT_DISSEMINATION_DENIED,
            request.user?.id ?? null,
            JSON.stringify({
              reason_code: exception.getResponse()?.['error_code'],
              http_status: status,
              document_id: request.params?.id ?? null,
            }),
          ],
        );
        await queryRunner.commitTransaction();
      } catch (auditError) {
        await queryRunner.rollbackTransaction();
        // Log erreur mais ne pas masquer l'exception originale
      } finally {
        await queryRunner.release();
      }
    }

    // Re-throw l'exception originale
    const response = ctx.getResponse();
    response.status(status).json(exception.getResponse());
  }
}

Différence avec v1 : logAsync remplacé par QueryRunner.startTransaction() + INSERT + commitTransaction(). La persistance est garantie AVANT le retour de la réponse HTTP (spec §5.8). La transaction est légère (1 INSERT) et n'impacte pas significativement la latence.

14. Politique de rétention des attestations (MAJ-04)¶

15. Contraintes techniques (MIN-04)¶

Dépendances inter-PD¶

Dépendances techniques¶

16. Compatibilité ESM/CJS (MAJ-08)¶

17. Variables CI requises (MIN-06)¶

18. Hors périmètre (inchangé)¶

Voir §10.

19. Mécanismes cross-module (inchangé)¶

Voir §11.

20. Périmètre de test (inchangé)¶

Voir §12.

PD-278 — Code Contracts (v2)¶

# PD-278-code-contracts.yaml
# Story: NF Z42-013 — ajout contractuel de l'état DIP
# Generated: 2026-03-01 (v2 — 19 écarts corrigés)

code_contracts:
  - module: dip-migration
    owner_agent: agent-migration
    interfaces: []
    invariants:
      - "INV-278-01: DIP ∈ enum document_status via ALTER TYPE ADD VALUE IF NOT EXISTS (l'enum DB contient aussi RESTITUTED PD-279)"
      - "INV-278-13: CHECK constraint dissemination_returned_at >= disseminated_at"
      - "INV-278-06: trigger WORM trg_motif_communication_worm bloque UPDATE motif_communication après insertion"
      - "INV-278-05: CREATE TABLE vault_secure.dissemination_attestations avec partitioning par année (issued_at)"
      - "Down migration bloquée si COUNT(*) WHERE status = 'DIP' > 0"
    forbidden:
      - "ALTER TYPE ADD VALUE dans un bloc BEGIN/COMMIT (spec PostgreSQL: DDL enum hors transaction)"
      - "Subquery dans clause WHERE d'un index partiel (REX PD-55: PostgreSQL l'interdit)"
      - "DROP TYPE document_status (PostgreSQL ne supporte pas DROP VALUE — spec DB)"
      - "Math.random() pour tout identifiant (REX PD-63: Sonar S2245 security hotspot)"
    architectural_decisions:
      - decision: "ALTER TYPE hors transaction + colonnes idempotentes IF NOT EXISTS"
        rationale: "Pattern établi PD-250/PD-279, PostgreSQL contraint ALTER TYPE ADD VALUE hors tx"
        alternatives_considered: ["Nouvelle table de mapping status", "Type VARCHAR au lieu d'enum"]
        trade_offs: ["Enum natif = performance + intégrité, mais non supprimable"]
      - decision: "Table dédiée dissemination_attestations avec partitioning RANGE(issued_at)"
        rationale: "Schéma riche §5.13, conservation 10 ans, partitioning = archivage + performance requêtes"
        alternatives_considered: ["Réutilisation integrity_journal_entries", "JSONB dans documents"]
        trade_offs: ["Table dédiée = surface plus large mais requêtes attestation indépendantes et archivage par année"]
    files:
      - "src/database/migrations/1741400000000-PD278-AddDipState.ts"

  - module: dip-attestation
    owner_agent: agent-entity
    interfaces:
      - DisseminationAttestation
    invariants:
      - "INV-278-05: 1 attestation par requête SEALED→DIP, stockée dans vault_secure.dissemination_attestations"
      - "Champs WORM: hash_evidence et signature_ref ne sont jamais modifiés après insertion"
      - "document_ids stocké en UUID[] pour lier N documents à 1 attestation"
      - "Rétention 10 ans, partitioning par année civile sur issued_at"
    forbidden:
      - "UPDATE sur hash_evidence ou signature_ref (WORM — intégrité cryptographique, spec §5.13)"
      - "DELETE sans politique d'archivage validée (conformité NF Z42-013 §8.3)"
      - "Stockage en clair de hash_evidence sans chiffrement au repos (sécurité: envelope encryption)"
    files:
      - "src/modules/documents/entities/dissemination-attestation.entity.ts"

  - module: dip-entity-extension
    owner_agent: agent-entity
    interfaces:
      - DocumentStatus
    invariants:
      - "INV-278-01: DocumentStatus enum contient DIP (DIP ∈ enum, pas vérification de cardinalité exacte)"
      - "Colonnes disseminated_at, disseminated_by, dissemination_returned_at, dissemination_package_id, motif_communication, retention_due déclarées dans l'entity"
    forbidden:
      - "Modifier les colonnes existantes de DocumentSecure (WORM, RLS, status existants — non-régression spec §2)"
      - "Supprimer ou renommer des colonnes PD-279 (restituted_at, restitution_deadline, geo_copy_count — non-régression PD-279 DONE)"
    files:
      - "src/modules/documents/entities/document-secure.entity.ts"

  - module: dip-state-machine
    owner_agent: agent-state-machine
    interfaces:
      - DocumentStateMachineService
    invariants:
      - "INV-278-09: SEALED → DIP et DIP → SEALED sont les seules nouvelles transitions"
      - "INV-278-08: EXPIRED reste terminal strict (aucune transition sortante applicative)"
      - "Transitions PENDING → DIP, DIP → EXPIRED, DIP → PENDING explicitement INTERDITES"
    forbidden:
      - "Modifier les transitions existantes PD-250/PD-279 (non-régression — PD-250 DONE, PD-279 DONE)"
      - "Ajouter une transition sortante de EXPIRED (INV-278-08 — spec §4.2 états terminaux)"
      - "Transition implicite timer/cron pour DIP → SEALED (INV-278-03 — spec §4.3 retour explicite uniquement)"
    files:
      - "src/modules/destruction/services/document-state-machine.service.ts"

  - module: dip-config
    owner_agent: agent-config
    interfaces:
      - DisseminationConfig
    invariants:
      - "Toutes les bornes numériques sont configurables via env vars avec defaults contractuels"
      - "Validation Joi avec min/max stricts — rejet startup si hors bornes (pas de clamping)"
    forbidden:
      - "Valeurs magiques en dur dans le code hardcoded MIN_COPIES, N_MAX, etc. (maintenabilité: config centralisée)"
      - "Clamping silencieux de valeurs hors bornes (sécurité: fail-fast au démarrage, spec §5.6)"
    files:
      - "src/modules/documents/config/dissemination.config.ts"

  - module: dip-dto
    owner_agent: agent-dto
    interfaces:
      - CreateDisseminationDto
      - DisseminationReturnDto
      - DisseminationResponseDto
      - DisseminationErrorDto
    invariants:
      - "CA-08: documents[] min 1 max N_MAX, rejet 422 hors bornes"
      - "motif_communication max 1024 chars UTF-8"
      - "Champs serveur (dissemination_package_id, disseminated_at, dissemination_returned_at) interdits en entrée"
    forbidden:
      - "Accepter des timestamps client (disseminated_at, returned_at) dans le DTO d'entrée (spec §5.1: horodatage serveur strict, CA-04)"
      - "Accepter dissemination_package_id dans le DTO d'entrée (spec §5.1: généré côté serveur uniquement)"
    files:
      - "src/modules/documents/dto/dissemination*.dto.ts"

  - module: dip-audit-types
    owner_agent: agent-audit
    interfaces:
      - AuditActionType
    invariants:
      - "3 nouveaux types: DOCUMENT_DISSEMINATED, DOCUMENT_RETURNED, DOCUMENT_DISSEMINATION_DENIED"
    forbidden:
      - "Modifier ou supprimer des AuditActionType existants (non-régression — types utilisés par d'autres modules)"
    files:
      - "src/modules/audit/types/audit-action.types.ts"

  - module: dip-journal-types
    owner_agent: agent-journal
    interfaces:
      - JournalEventType
    invariants:
      - "2 nouveaux types: DIP_DISSEMINATED, DIP_RETURNED"
    forbidden:
      - "Modifier ou supprimer des JournalEventType existants (non-régression — types utilisés par IntegrityJournalService)"
    files:
      - "src/modules/integrity/enums/journal-event-type.enum.ts"

  - module: dip-rate-limit
    owner_agent: agent-rate-limit
    interfaces:
      - DisseminationRateLimitGuard
    invariants:
      - "INV-278-02: rate-limit 60 req/min + quota 1000 req/jour par acteur (configurable)"
      - "Fail-closed: si Redis indisponible → 503 E-503-REDIS (pas de bypass)"
      - "Rejet 429 déclenche audit DOCUMENT_DISSEMINATION_DENIED via exception filter synchrone C11"
    forbidden:
      - "Enregistrer le guard en APP_GUARD global, scope controller uniquement (sécurité: rate-limit ciblé DIP, pas global)"
      - "Fail-open si Redis down (sécurité: fail-closed obligatoire — INV-278-02, OWASP rate-limiting)"
      - "Rate-limit par document_id au lieu de acteur_id (spec §5.7: quota par acteur, pas par document)"
    architectural_decisions:
      - decision: "Redis INCR + EXPIRE (sliding window) par acteur, pattern LegalRateLimitGuard"
        rationale: "Pattern établi PD-81, performant, fail-closed cohérent"
        alternatives_considered: ["Table PostgreSQL pour quota", "In-memory counter"]
        trade_offs: ["Redis = dépendance externe mais déjà en place"]
    files:
      - "src/modules/documents/guards/dissemination-rate-limit.guard.ts"

  - module: dip-service
    owner_agent: agent-core
    interfaces:
      - DisseminationService
    invariants:
      - "INV-278-02: 6 gardes séquentielles (état, copies, retention, auth/role implicites via guards, RLS via SET LOCAL)"
      - "INV-278-04: outbox audit INSERT synchrone dans la même transaction que UPDATE status"
      - "INV-278-05: 1 attestation par requête, insérée dans vault_secure.dissemination_attestations dans la même transaction"
      - "INV-278-06: aucune mutation contenu en DIP"
      - "INV-278-11: package atomique — 1 échec = ROLLBACK global"
      - "INV-278-12: SELECT FOR UPDATE ordonné par document_id ASC (// LOCK-ORDER: document_id ASC §5.9)"
      - "INV-278-13: returned_at = GREATEST(NOW(), disseminated_at)"
      - "INV-278-14: garde retention_due=false sur SEALED→DIP ; retention_service BYPASSRLS pour clôture DIP→SEALED"
    forbidden:
      - "Promise.all sur les vérifications de gardes, séquentiel obligatoire pour diagnostic (spec §5.4: erreur explicite par garde)"
      - "Mutation du contenu documentaire (encrypted_metadata, file_hash, ovh_path) en DIP (INV-278-06: WORM)"
      - "Attestation ou audit hors de la transaction ACID (INV-278-05: atomicité spec §5.13)"
      - "Timeout implicite DIP → SEALED par scheduler/cron (INV-278-03: retour explicite uniquement, spec §4.3)"
      - "Utiliser Math.random() pour package_id, attestation_id (REX PD-63: Sonar S2245, crypto.randomUUID() obligatoire)"
      - "Cache applicatif pour retention_due, lecture directe DB (spec §5.11: source de vérité = DB, fenêtre de race 5 min max)"
    architectural_decisions:
      - decision: "QueryRunner explicite avec SELECT FOR UPDATE ordonné, pattern RestitutionService"
        rationale: "Pattern établi PD-279, atomicité ACID + prévention deadlock par tri lexicographique"
        alternatives_considered: ["DataSource.transaction() wrapping", "Optimistic locking par version"]
        trade_offs: ["QueryRunner = plus verbose mais contrôle total sur verrouillage et RLS"]
      - decision: "Table dédiée vault_secure.dissemination_attestations pour attestations (vs lifecycle_log)"
        rationale: "Schéma riche §5.13 (hash_evidence, signature_ref, document_ids array), conservation 10 ans"
        alternatives_considered: ["Réutilisation integrity_journal_entries", "Colonne JSONB dans documents"]
        trade_offs: ["Table dédiée = plus de surface, mais requêtes attestation indépendantes"]
    files:
      - "src/modules/documents/services/dissemination.service.ts"

  - module: dip-controller
    owner_agent: agent-controller
    interfaces:
      - DisseminationController
    invariants:
      - "POST /api/v1/documents/disseminations pour SEALED → DIP"
      - "POST /api/v1/documents/{id}/dissemination-return pour DIP → SEALED"
      - "Guards: JwtAuthGuard + AuthorizationGuard + DisseminationRateLimitGuard (F1)"
      - "Guards: JwtAuthGuard + AuthorizationGuard (F2, roles incluant retention_service)"
    forbidden:
      - "GET endpoint qui modifie l'état, side effects (REST: safe methods = pas de mutation, spec §5.2)"
      - "Bypass de ParseUUIDPipe sur document_id (sécurité: validation stricte UUID, E-400-ID-FORMAT)"
      - "Enregistrement dans un module autre que DocumentsModule (architecture: cohérence modulaire NestJS)"
    files:
      - "src/modules/documents/controllers/dissemination.controller.ts"

  - module: dip-exception-filter
    owner_agent: agent-filter
    interfaces:
      - DisseminationAuditExceptionFilter
    invariants:
      - "INV-278-04: audit DOCUMENT_DISSEMINATION_DENIED pour 401, 403, 429, 409-RETENTION-DUE"
      - "Persistance SYNCHRONE via QueryRunner dédié (spec §5.8: transaction légère BEGIN/INSERT/COMMIT)"
      - "Persistance garantie AVANT le retour de la réponse HTTP"
      - "Exclure les codes déjà audités par le service (éviter double audit)"
    forbidden:
      - "Swallow d'exceptions sans re-throw (sécurité: l'appelant doit recevoir l'erreur originale)"
      - "logAsync pour les refus sécurité (spec §5.8: persistance synchrone obligatoire via QueryRunner dédié)"
    files:
      - "src/modules/documents/filters/dissemination-audit-exception.filter.ts"

  - module: dip-tla-formal
    owner_agent: agent-formal
    interfaces: []
    invariants:
      - "CA-10: DIP ∈ DocStates dans le modèle TLA+"
      - "TLC vérifie DocStates ⊆ RealStates sans violation"
    forbidden:
      - "Modifier _AnchoredFacts.tla directement (généré par CI, modifier norm.yaml — architecture CI/CD)"
      - "Supprimer des états existants du modèle (non-régression: états validés par TLC)"
    files:
      - "ProbatioVault-doc/docs/normes/nf-z42-013/formal/NF_Z42_013.tla"

  - module: dip-tests
    owner_agent: agent-tests
    interfaces: []
    invariants:
      - "Tous TC-INV-01 à TC-INV-13 implémentés en Given/When/Then"
      - "Tests concurrence (TC-INV-12) avec parallel requests réels"
      - "Tests atomicité package (TC-INV-11) avec injection d'échec"
      - "TC-FML-01 (TLA+ TLC) et TC-FML-02 (tests contractuels) inclus"
      - "TC-NOM-07 (package_id mono/multi) inclus"
      - "Framework: Jest + ts-jest"
    forbidden:
      - "Mocks qui masquent le comportement PostgreSQL réel (RLS, triggers, locks) — tests d'intégration = DB réelle obligatoire"
      - "Tests qui dépendent d'un ordre d'exécution non déterministe (fiabilité: tests reproductibles)"
      - "Skip de tests concurrence ou atomicité (INV-278-11/12: invariants critiques, skip = violation constitutionnelle)"
    files:
      - "src/modules/documents/services/dissemination.service.spec.ts"
      - "src/modules/documents/controllers/dissemination.controller.spec.ts"
      - "src/modules/documents/guards/dissemination-rate-limit.guard.spec.ts"
      - "src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts"

Résumé exécutif v2 : 13 composants + 1 entity attestation (dip-attestation), 5 phases (0–4), 14 invariants mappés à des mécanismes techniques concrets, 49 tests contractuels couverts (dont TC-FML-01/02 et TC-NOM-07), 0 transition implicite, atomicité ACID garantie par QueryRunner + SELECT FOR UPDATE ordonné. Audit refus sécurité synchrone (spec §5.8) via QueryRunner dédié. Table vault_secure.dissemination_attestations avec partitioning annuel et rétention 10 ans. Enum DB 5 valeurs (incluant RESTITUTED PD-279) — tests vérifient DIP ∈ enum_range (pas cardinalité = 4). Convention verrouillage cross-module documentée (pas d'abstraction, commentaire // LOCK-ORDER). Codes erreur enrichis : 404 (not found), 503 (Redis fail-closed). BYPASSRLS retention_service contractualisé. Compatibilité ESM/CJS documentée. Variables CI listées. Le plan réutilise les patterns établis PD-279 (RestitutionService), PD-250 (migration enum), PD-81 (rate-limit Redis) et PD-60 (exception filter audit).