> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corelink.dhi-cm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sécurité des Échanges

> Cette section définit les formats standardisés, les en-têtes de sécurité et les règles cryptographiques applicables à tous les échanges entre le Connecteur et les Banques.

<Note>
  **Aucune requête ou réponse ne peut être traitée sans respecter ces règles.**
</Note>

## Authentication

Le protocole OAuth 2 est le mécanisme supporté pour cette couche d'authentification :

**OAuth 2.0 (client\_credentials) :  Mécanisme standardisé et recommandé**, où les identifiants clients sont échangés contre un **jeton JWT** (JSON Web Token). Ce jeton est ensuite utilisé dans l'en-tête Authorization: Bearer \<token>.

## Protection anti-rejeu

Prévention des attaques par relecture de messages

### Principe

Chaque message doit contenir :

* un identifiant unique `nonce`),
* un horodatage `timestamp`).

### Règles de validation

* Le `nonce` doit être **unique**
* Le timestamp doit être au format **RFC3339 UTC**
* La dérive horaire maximale autorisée est configurable (par défaut ±120s)

### Comportement attendu

Tout message :

* avec un nonce déjà utilisé,
* ou un timestamp expiré,

doit être rejeté avec une erreur de sécurité.

## Idempotence

Garantie d’exécution unique des ordres

### Objectif

L’idempotence garantit qu’un même ordre métier ne sera **jamais exécuté plus d’une fois**.

### Clé d’idempotence

Chaque requête doit inclure :

* une clé d’idempotence unique,
* stable sur toute la durée de vie de l’ordre.

### Règles

* La Banque doit stocker la clé et le résultat associé
* Toute requête dupliquée retourne le résultat initial
* Aucun retraitement métier ne doit être déclenché

## Signature des messages (JWS)

Garantie d’intégrité et de non-répudiation

### Objectif

Chaque message échangé doit être \*\*signé numériquement \*\* afin de garantir :

* l’intégrité du contenu,
* l’authenticité de l’émetteur,
* la non-répudiation.

### Standard utilisé

* **JSON Web Signature (JWS)**
* Algorithmes autorisés : `RS256`, `PS256`

### Règles obligatoires

* La signature porte sur **l’intégralité du payload métier**
* Toute modification invalide la signature
* Une signature invalide entraîne un rejet immédiat

### Responsabilités Banque

* Signer les callbacks de statut
* Vérifier les signatures des ordres entrants

## En-têtes HTTP de sécurité (Push / Pull)

Ces en-têtes **DOIVENT être  validés avant tout traitement métier**.

| En-tête             | Rôle                        | Format        | Générateur |
| :------------------ | :-------------------------- | :------------ | :--------- |
| `X-Client-Id`       | Identification              | String        | Les deux   |
| `X-Request-Id`      | Tracabilité                 | String opaque | Client     |
| `X-Timestamp`       | Anti-replay                 | ISO-8601 UTC  | Les deux   |
| `X-Nonce`           | Anti-replay                 | String opaque | Les deux   |
| `X-Idempotency-Key` | Idempotence                 | String opaque | Client     |
| `X-Signature`       | Intégrité / Non-répudiation | JWS detached  | Les deux   |

## 4.3 Construction du message par l’émetteur (CRITIQUE)

Cette section décrit **exactement comment le body est calculé et signé**.

<Warning>
  **Toute implémentation DOIT suivre ces étapes dans cet ordre.**
</Warning>

### Étape A — Canonicalisation du payload

1. Le payload JSON est **canonicalisé** via :
   * **JCS (JSON Canonicalization Scheme – RFC 8785)**
2. Le hash est calculé :

```
payloadHash = SHA-256(JCS(payload))
```

Cela garantit :

* ordre des champs déterministe
* absence d’ambiguïté cryptographique

### Étape B — Construction du Header Protégé JWS

La signature **DOIT couvrir les éléments suivants** :

| Claim JWS     | Source              | Rôle                   |
| :------------ | :------------------ | :--------------------- |
| `alg`         | JWS                 | Algorithme (ex: ES384) |
| `kid`         | JWS                 | Identifiant de clé     |
| `timestamp`   | `X-Timestamp`       | Anti-replay            |
| `nonce`       | `X-Nonce`           | Anti-replay            |
| `idempotency` | `X-Idempotency-Key` | Unicité                |
| `payloadhash` | Calculé             | Intégrité du body      |

### Étape C — Génération de la signature (`X-Signature`)

* La signature est générée avec :
  * la **clé privée** de l’émetteur
  * stockée dans un **HSM / Vault**
* Le format est :
  * **JWS detached** (le payload n’est pas encodé dans la signature)

Le résultat est placé dans :

```yaml theme={null}
X-Signature: <jws-detached>
```

## 4.4 Validation du message par le destinataire

Les validations sont exécutées **dans l’ordre strict ci-dessous**.

### 4.4.1 Contrôles anti-replay et temporels

| En-tête       | Règle                  | Code d’erreur           |
| :------------ | :--------------------- | :---------------------- |
| `X-Timestamp` | now − timestamp ≤ 120s | `SEC_TIMESTAMP_EXPIRED` |
| `X-Nonce`     | Unique sur 300s        | `SEC_REPLAY_DETECTED`   |

### 4.4.2 Contrôle d’intégrité (Signature JWS)

1. Identification de la clé publique (`X-Client-Id` / `kid`)
2. Vérification de la signature JWS
3. Recalcul du `payloadHash`
4. Comparaison avec le `payloadhash` signé

| Échec              | Code                    |
| :----------------- | :---------------------- |
| Signature invalide | `SEC_INVALID_SIGNATURE` |
| Hash différent     | `PAYLOAD_HASH_MISMATCH` |

### 4.4.3 Contrôle d’idempotence métier

* La `X-Idempotency-Key` est utilisée comme **clé métier**
* Si déjà traitée avec un statut final :
  * **le traitement N’EST PAS rejoué**
  * le résultat initial est retourné
* Sinon :
  * traitement métier
  * stockage du résultat avec TTL

## 4.5 Principe clé

> **Le body n’est jamais signé directement.C’est le hash du body canonicalisé qui est signé.**