PD-60 — Plan d'implémentation : Dépôt probatoire d'un document (Upload)¶

Référence spec : PD-60-specification.md (v2 — amendée 3 février 2026, incluant INV-60-15..17 et CA-60-19..21). Toutes les règles référencées ci-dessous (INV-60-01..17, CA-60-01..21, ERR-60-01..12) sont présentes dans la spécification canonique amendée.

1. Découpage en composants¶

Composants impactés¶

Endpoints¶

Nouveaux fichiers¶

src/modules/documents/
├── controllers/
│   └── deposit.controller.ts
├── dto/
│   ├── create-deposit.dto.ts
│   └── deposit-response.dto.ts
├── entities/
│   ├── deposit.entity.ts
│   └── deposit-staging.entity.ts
├── services/
│   ├── deposit.service.ts
│   ├── proof-receipt.service.ts
│   ├── deposit-audit.service.ts
│   └── ntp-health.service.ts
└── __tests__/
    ├── deposit.controller.spec.ts
    ├── deposit.service.spec.ts
    ├── proof-receipt.service.spec.ts
    └── deposit-audit.service.spec.ts

2. Flux techniques¶

FN-60-01 — Confirmation probatoire nominale¶

Client                    DepositController      DepositService       ProofReceiptService    AuditModule        S3
  │                             │                      │                     │                  │              │
  │ POST /documents/upload      │                      │                     │                  │              │
  │ [JWT + body multipart]      │                      │                     │                  │              │
  │────────────────────────────>│                      │                     │                  │              │
  │                             │ validate DTO         │                     │                  │              │
  │                             │ (class-validator)    │                     │                  │              │
  │                             │─────────────────────>│                     │                  │              │
  │                             │                      │ 1. Check auth+RLS   │                  │              │
  │                             │                      │ 2. Check notice_ack │                  │              │
  │                             │                      │    + notice_text    │                  │              │
  │                             │                      │ 3. SHA-256(content) │                  │              │
  │                             │                      │    == fingerprint?  │                  │              │
  │                             │                      │ 4. Check idempotence│                  │              │
  │                             │                      │    (client_request_id)                 │              │
  │                             │                      │ 5. Check NTP health │                  │              │
  │                             │                      │                     │                  │              │
  │                             │                      │ 6. Store content ───────────────────────────────────>│
  │                             │                      │                     │                  │              │
  │                             │                      │ 7. Write audit ─────────────────────>│              │
  │                             │                      │    (append-only +   │                  │ HSM sign     │
  │                             │                      │     HSM signature)  │                  │              │
  │                             │                      │    ← audit_result   │                  │              │
  │                             │                      │                     │                  │              │
  │                             │                      │ 8. Generate JWS ───>│  (tenté INDÉPENDAMMENT         │
  │                             │                      │                     │   du résultat audit)            │
  │                             │                      │                     │ sign(payload,    │              │
  │                             │                      │                     │  HSM private key)│              │
  │                             │                      │                     │<── receipt_result │              │
  │                             │                      │                     │                  │              │
  │                             │                      │ 9. Check double     │                  │              │
  │                             │                      │    condition :      │                  │              │
  │                             │                      │    audit OK AND     │                  │              │
  │                             │                      │    receipt OK ?     │                  │              │
  │                             │                      │    → OUI: INSERT deposit (PROBATIVE_DEPOSIT)          │
  │                             │                      │    → NON: INSERT staging (NON_PROBATIVE_STAGING)       │
  │                             │                      │                     │                  │              │
  │                             │<─────────────────────│                     │                  │              │
  │ 201 Created                 │                      │                     │                  │              │
  │ { deposit_id, timestamp,    │                      │                     │                  │              │
  │   proof_receipt, ... }      │                      │                     │                  │              │
  │<────────────────────────────│                      │                     │                  │              │

FN-60-03 — Contexte dégradé (staging)¶

  DepositService tente audit ET receipt indépendamment.
  Si l'un ou l'autre échoue (ou les deux) :
  → INSERT deposit_stagings (NON_PROBATIVE_STAGING, degraded_reason indique le(s) composant(s) en échec)
  → Retourne staging_id, act_type=NON_PROBATIVE_STAGING
  → PAS de deposit_id, PAS de proof_receipt, PAS de timestamp

FN-60-04 — Confirmation après staging¶

  Client rejoue POST /documents/upload avec même client_request_id
  → DepositService détecte staging existant + conditions OK
  → Applique FN-60-01 (promotion staging → deposit)
  → DELETE staging, INSERT deposit

ERR-60-09 — Demande de preuve sur staging¶

  Client appelle GET /documents/deposits/:staging_id/proof
  → DepositService cherche par id dans deposits (non trouvé)
  → DepositService cherche par id dans deposit_stagings (trouvé, act_type=NON_PROBATIVE_STAGING)
  → Refus explicite : HTTP 400 { error: "PROOF_NOT_AVAILABLE", message: "staging has no probative status" }
  → Audit entry : DEPOSIT_PROOF_REFUSED_STAGING

2b. Diagrammes Mermaid¶

Graphe de dépendances des modules¶

graph TD
    Client([Client HTTP])

    subgraph DocumentsModule
        DC[DepositController]
        DS[DepositService]
        PRS[ProofReceiptService]
        DAS[DepositAuditService]
        NTHS[NtpHealthService]
    end

    subgraph Modules existants
        AM[AuditModule]
        CM[CryptoModule / HashService]
        UM[UploadModule]
        SM[StorageModule / S3]
        AuthM[AuthModule / JWT + RLS]
    end

    subgraph Persistance
        DB[(PostgreSQL<br/>deposits + deposit_stagings)]
    end

    Client -->|POST /documents/upload<br/>GET /deposits/:id/proof| DC
    DC --> AuthM
    DC --> DS
    DS --> CM
    DS --> NTHS
    DS --> UM
    DS --> SM
    DS --> DAS
    DS --> PRS
    DS --> DB
    DAS --> AM
    PRS --> CM
    AM -->|HSM sign| CM

Séquence — Dépôt probatoire nominal (FN-60-01)¶

sequenceDiagram
    actor C as Client
    participant DC as DepositController
    participant Auth as AuthModule
    participant DS as DepositService
    participant CM as CryptoModule
    participant NTHS as NtpHealthService
    participant SM as StorageModule (S3)
    participant DAS as DepositAuditService
    participant PRS as ProofReceiptService
    participant DB as PostgreSQL

    C->>DC: POST /documents/upload [JWT + multipart]
    DC->>Auth: Validate JWT + extract RLS context
    Auth-->>DC: userId, vaultId
    DC->>DS: createDeposit(dto, user)

    DS->>DS: Validate notice_ack + notice_text
    DS->>CM: SHA-256(content)
    CM-->>DS: fingerprint
    DS->>DS: Compare fingerprint vs dto.fingerprint
    DS->>DS: Check idempotence (client_request_id)
    DS->>NTHS: checkDrift()
    NTHS-->>DS: NTP OK

    DS->>SM: store(content, key)
    SM-->>DS: s3_key

    par Audit + Receipt (indépendants)
        DS->>DAS: writeAudit(DEPOSIT_CREATED, metadata)
        DAS-->>DS: audit OK
    and
        DS->>PRS: generateReceipt(payload)
        PRS->>CM: HSM sign(payload)
        CM-->>PRS: JWS
        PRS-->>DS: proof_receipt
    end

    alt audit OK AND receipt OK
        DS->>DB: INSERT deposits (PROBATIVE_DEPOSIT)
    else un ou les deux en échec
        DS->>DB: INSERT deposit_stagings (NON_PROBATIVE_STAGING)
    end

    DS-->>DC: depositResult
    DC-->>C: 201 Created {deposit_id, timestamp, proof_receipt}

Séquence — Confirmation après staging (FN-60-04)¶

sequenceDiagram
    actor C as Client
    participant DS as DepositService
    participant DAS as DepositAuditService
    participant PRS as ProofReceiptService
    participant DB as PostgreSQL

    C->>DS: POST /documents/upload (même client_request_id)
    DS->>DB: Lookup staging par client_request_id
    DB-->>DS: staging trouvé

    DS->>DAS: writeAudit(DEPOSIT_CREATED, metadata)
    DAS-->>DS: audit OK
    DS->>PRS: generateReceipt(payload)
    PRS-->>DS: proof_receipt

    alt double condition OK
        DS->>DB: DELETE deposit_stagings
        DS->>DB: INSERT deposits (PROBATIVE_DEPOSIT)
        DS-->>C: 201 Created {deposit_id, proof_receipt}
    else échec persistant
        DS->>DB: UPDATE deposit_stagings (degraded_reason)
        DS-->>C: 201 Created {staging_id, NON_PROBATIVE_STAGING}
    end

3. Mapping invariants → mécanismes¶

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

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

Tests nominaux¶

Tests d'erreur¶

Tests d'invariants¶

Tests de non-régression¶

Tests adversariaux¶

6. Gestion des erreurs¶

7. Impacts sécurité¶

8. Hypothèses techniques¶

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

1. Latence HSM en Phase A (TX ouverte) : Les signatures HSM (audit + receipt) sont exécutées en Phase A, à l'intérieur de la transaction englobante (voir INV-60-02). La TX reste ouverte pendant les appels HSM, ce qui maintient le verrou advisory mais allonge la durée de la TX. Si la latence HSM > 500ms, la TX est plus longue mais l'atomicité et la sérialisation restent garanties. Mitigation : timeout configurable par opération HSM (avec ROLLBACK en cas de timeout), monitoring latence HSM, alerte si durée TX > seuil.

2. Taille du contenu opaque : La spec ne définit pas de limite de taille. L'UploadModule existant gère le multipart streaming mais la vérification SHA-256 serveur nécessite de hasher tout le contenu. Pour des fichiers > 1 Go, utiliser un hash streaming (déjà disponible via HashStreamService).

3. Migration des documents existants : Les DocumentSecure existants n'ont pas de deposit_id ni de proof_receipt. PD-60 crée de nouvelles tables (deposits, deposit_stagings), pas de migration des données existantes.

4. Clé publique JWKS : L'endpoint /documents/.well-known/jwks.json expose la clé publique. Il doit être public (pas de JWT requis) mais protégé contre les abus (rate-limiting infra, cache CDN). C'est le mécanisme unique de distribution de la clé publique pour la vérification tiers (HT-08).

5. Concurrence sur client_request_id (sérialisation inter-table) : Deux requêtes simultanées avec le même (user_id, client_request_id) sont sérialisées par pg_advisory_xact_lock(hashtext(user_id::text || '/' || client_request_id)) (Phase 0). Ce verrou couvre les deux tables (deposits et deposit_stagings), empêchant qu'un même (user_id, client_request_id) produise un deposit dans une table et un staging dans l'autre par interleaving concurrent. La deuxième requête attend la libération du verrou puis applique la logique idempotence/conflit sur l'état résultant.

6. NTP monitoring : Le NtpHealthService doit être un health check périodique (cron toutes les 30s), pas un appel NTP par requête. Le statut est mis en cache.

10. Hors périmètre¶

• Consultation, modification, partage, suppression, recherche, versioning (PD-61 à PD-69)
• Rate-limiting sur l'endpoint upload (relève de l'infra — PC-60-17)
• Résistance admin-level de l'append-only audit — explicitement hors périmètre de cette US par décision contractuelle PC-60-13 (spec §4 INV-60-06 : « La non-altérabilité absolue (résistance à un acteur disposant d'un accès administrateur au stockage) est hors périmètre de cette US et relève de l'infrastructure »). Cette exclusion est actée dans la spec canonique, pas une hypothèse du plan.
• Qualification juridictionnelle de la valeur probatoire
• Définition des performances (latence, débit, volumétrie)
• Gestion des clés de signature (rotation, publication) — relève du module crypto existant

Schéma base de données¶

Table vault_secure.deposits¶

CREATE TABLE vault_secure.deposits (
  id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),  -- deposit_id
  user_id        UUID NOT NULL REFERENCES vault_secure.users(id),
  client_request_id  VARCHAR(255) NOT NULL,
  document_fingerprint VARCHAR(64) NOT NULL,  -- SHA-256 hex lowercase
  existence_timestamp_utc TIMESTAMPTZ NOT NULL,
  depositor_identity_ref UUID NOT NULL,  -- == user_id (JWT.sub)
  responsibility_scope_ref VARCHAR(255) NOT NULL,  -- JWT.tenant_id (obligatoire)
  proof_receipt   TEXT NOT NULL,  -- JWS compact
  audit_trace_ref UUID NOT NULL,  -- FK audit_log.id
  act_type        VARCHAR(30) NOT NULL DEFAULT 'PROBATIVE_DEPOSIT',
  legal_existence_status VARCHAR(30) NOT NULL DEFAULT 'ESTABLISHED',
  storage_path    VARCHAR(512) NOT NULL,  -- S3 path
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  CONSTRAINT uq_deposits_client_request UNIQUE (user_id, client_request_id)
);

-- RLS
ALTER TABLE vault_secure.deposits ENABLE ROW LEVEL SECURITY;
CREATE POLICY deposits_user_isolation ON vault_secure.deposits
  USING (user_id = current_setting('app.current_user_id')::uuid);

Sérialisation inter-table (applicative, Phase 0 — dans la TX englobante) :

-- Exécuté en Phase 0, DANS la transaction explicite (BEGIN déjà émis)
-- Le verrou est maintenu jusqu'au COMMIT ou ROLLBACK de cette TX
SELECT pg_advisory_xact_lock(hashtext(user_id::text || '/' || client_request_id));

Logique d'idempotence/conflit (applicative, sous verrou advisory) : - SELECT par (user_id, client_request_id) dans deposits → si existe : - document_fingerprint identique → retourner le deposit existant (CA-60-06, ERR-60-08) - document_fingerprint différent → HTTP 409 (CA-60-07, ERR-60-05) - Si n'existe pas → SELECT dans deposit_stagings : - Staging trouvé avec même fingerprint + conditions OK → promouvoir (FN-60-04) - Staging trouvé avec fingerprint différent → HTTP 409 (ERR-60-12) - Rien trouvé → nouveau dépôt (FN-60-01)

Table vault_secure.deposit_stagings¶

CREATE TABLE vault_secure.deposit_stagings (
  id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),  -- staging_id
  user_id        UUID NOT NULL REFERENCES vault_secure.users(id),
  client_request_id  VARCHAR(255) NOT NULL,
  document_fingerprint VARCHAR(64) NOT NULL,
  storage_path    VARCHAR(512) NOT NULL,
  act_type        VARCHAR(30) NOT NULL DEFAULT 'NON_PROBATIVE_STAGING',
  legal_existence_status VARCHAR(30) NOT NULL DEFAULT 'NOT_ESTABLISHED',
  degraded_reason VARCHAR(255),  -- Reason for degraded context
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  CONSTRAINT uq_stagings_client_request UNIQUE (user_id, client_request_id)
);

-- RLS
ALTER TABLE vault_secure.deposit_stagings ENABLE ROW LEVEL SECURITY;
CREATE POLICY stagings_user_isolation ON vault_secure.deposit_stagings
  USING (user_id = current_setting('app.current_user_id')::uuid);

Ordre d'implémentation¶

Tailles : S = petite, M = moyenne, L = grande

Références¶

• Spécification : PD-60-specification.md (v2 — amendée 3 février 2026, incluant INV-60-15..17 et CA-60-19..21)
• Tests contractuels : PD-60-tests.md
• Review spécification : PD-60-specification-review.md
• Epic : PD-192 — API Documents & preuves probatoires
• Architecture existante : NestJS 10.3 + TypeORM 0.3 + PostgreSQL + CloudHSM (PD-7)