Contrat push de l'alerte de sûreté MIK

Cette page s'adresse à l'équipe qui exploite le système émettant l'alerte de sûreté du navire (SSA) vers l'exemple MIK mer du Nord. Elle décrit exactement ce que vérifie le côté récepteur, pour qu'un émetteur puisse être construit à partir d'elle. Tout ce qui suit est déduit du code qui reçoit la livraison ; la dernière section nomme le fichier de chaque règle. Rien ici n'est une procédure opérationnelle : les champs suivent le plan public d'une SSA (chapitre XI-2, règle 6 de SOLAS, et Code ISPS) et rien de plus.

Le récepteur est le mode d'ingestion push de la source de données mik-ssa-alerts-v1. Les mécanismes génériques de ce mode (adresse, ordre, livraisons mises de côté) sont décrits dans Modes d'ingestion ; cette page est le contrat de cette source précise.

Ce qu'il faut obtenir du côté récepteur

Une livraison

Une requête porte un objet JSON dont le tableau alerts contient les alertes (normalement une). Envoyez un tableau : une valeur alerts qui est un objet unique au lieu d'un tableau est aussi lue, comme une seule alerte, mais cela ne fait pas partie du contrat. Trois en-têtes portent l'identité, l'heure de signature et la signature :

Les noms d'en-têtes sont comparés sans tenir compte de la casse, comme tous les noms d'en-têtes HTTP. Envoyez Content-Type: application/json.

{
  "alerts": [
    {
      "alertId": "3f0c7c2e-8d1a-4b6e-9a52-7e1d2c4b8f10",
      "mmsi": "000000002",
      "imo": "9000002",
      "shipName": "Demo Aurora Tide",
      "callsign": null,
      "latitude": 51.62,
      "longitude": 2.71,
      "alertedAt": "2026-10-14T00:00:00.000Z",
      "status": "active",
      "provenance": "demo sender"
    }
  ]
}

Champs

Chaque alerte est un objet avec ces champs. Les champs inconnus sont ignorés. Les types sont vérifiés alerte par alerte une fois la livraison acceptée (voir Réponses).

Le récepteur ne vérifie ni l'intervalle ni le système géodésique d'une coordonnée : envoyez du WGS 84 et gardez vous-même la latitude entre -90 et 90 et la longitude entre -180 et 180. Un imo ou un callsign absent est stocké comme null.

Alerte et annulation

Il n'y a qu'une forme de message et qu'un point d'entrée. Les deux messages ne diffèrent que par status :

• Alerte : status vaut "active". Un nouvel alertId crée une ligne.
• Annulation : le même corps avec le même alertId et status à "cancelled", envoyé comme nouvelle livraison (nouvel identifiant de livraison). La source écrit en upsert sur alertId : l'annulation remplace la ligne de l'alerte. Répétez tous les champs obligatoires : la ligne est remplacée en bloc, et alertedAt doit garder la valeur d'origine de l'alerte. La comparaison est exacte et en minuscules ; toute autre valeur est stockée telle quelle et n'est pas une annulation.

La surveillance qui lève une détection à partir des alertes écarte à la lecture toute alerte dont status vaut "cancelled" : une alerte annulée ne lève aucune détection et n'apparaît pas dans l'application. Une annulation ne retire pas une détection ou un dossier que l'alerte active a déjà ouvert : la surveillance ne lit plus cette ligne, elle n'agit donc pas dessus. Ce contrat ne décide pas si une annulation doit retirer quelque chose.

Horodatage

• x-ssa-signature-timestamp est en secondes Unix UTC (le même instant partout sur Terre ; il n'y a pas de fuseau à choisir).
• Le récepteur accepte une livraison dont l'heure de signature est à 300 secondes ou moins de sa propre horloge, dans les deux sens, bornes comprises. Au-delà, la réponse est 401 push_signature_stale et rien n'est lu dans le corps.
• Gardez l'horloge de l'émetteur synchronisée (NTP). Une reprise reçoit un horodatage neuf et le même identifiant de livraison ; l'horodatage ne fait pas partie de l'identité d'une livraison.
• alertedAt est autre chose : le moment où l'alerte a été déclenchée à bord. Le récepteur ne le compare pas à l'horloge. La surveillance de détection de l'exemple, en revanche, ne lit que les alertes dont alertedAt date de moins de 900 secondes : une alerte horodatée plus ancienne est stockée mais ne lève aucune détection.

Signature

La signature couvre ces octets, dans cet ordre, sans rien ajouter :

<x-ssa-signature-timestamp>.<x-ssa-alert-id>.<le corps de la requête, octet pour octet>

Le condensat est HMAC-SHA256(clé = le secret en UTF-8, message = ces octets), envoyé en hexadécimal, éventuellement préfixé par sha256=. Un autre préfixe que sha256= est refusé. Le corps est signé tel qu'envoyé : il n'y a pas de forme canonique, donc signez les octets finaux après sérialisation et envoyez exactement ceux-là.

Comme l'horodatage et l'identifiant de livraison sont dans les octets signés, une requête capturée ne peut être rejouée ni plus tard ni sous un autre identifiant de livraison. Il y a un secret par source installée. Le récepteur résout la connexion à neuf pour chaque livraison : changer le secret revient à modifier la connexion ; la première livraison suivante est vérifiée avec la nouvelle valeur, et il n'existe pas de période de recouvrement où les deux secrets seraient acceptés.

Un exemple détaillé. Avec le secret example-shared-secret, l'identifiant de livraison 7d0f3c2e-5b1a-4a8e-9f61-2c4b8e1d0a93 et l'horodatage 1791936000 (2026-10-14T00:00:00Z), la signature du corps ci-dessus sur une seule ligne et sans saut de ligne final donne :

BODY='{"alerts":[{"alertId":"3f0c7c2e-8d1a-4b6e-9a52-7e1d2c4b8f10","mmsi":"000000002","imo":"9000002","shipName":"Demo Aurora Tide","callsign":null,"latitude":51.62,"longitude":2.71,"alertedAt":"2026-10-14T00:00:00.000Z","status":"active","provenance":"demo sender"}]}'
DELIVERY_ID='7d0f3c2e-5b1a-4a8e-9f61-2c4b8e1d0a93'
TS=1791936000
printf '%s.%s.%s' "$TS" "$DELIVERY_ID" "$BODY" | openssl dgst -sha256 -hmac 'example-shared-secret'
# 9e783debd3c597b8cb4b5797c47cc9a4e05b727fda23363d8ef7dc9ba66d0291

La requête porte alors x-ssa-signature: sha256=9e783debd3c597b8cb4b5797c47cc9a4e05b727fda23363d8ef7dc9ba66d0291.

Réponses

Les vérifications s'exécutent dans cet ordre ; la première qui échoue répond.

Un 202 signifie que la livraison est en file, pas que chaque alerte qu'elle contient est stockée. Après l'acceptation, chaque alerte est vérifiée selon le tableau des champs ci-dessus : une alerte qui y déroge (un nombre là où mmsi doit être une chaîne, un alertedAt sans fuseau, un champ obligatoire absent) est mise de côté seule, conservée une heure, et les autres alertes de la livraison sont écrites. Un émetteur qui veut la confirmation qu'une alerte est arrivée dans la table doit lire la table ou la santé de la source dans Analytics ; la réponse ne le dit pas.

Reprises et idempotence

• Même identifiant de livraison, mêmes alertes (l'horodatage et la signature peuvent différer, et les octets bruts du corps aussi : ce qui est comparé, ce sont les lignes auxquelles le corps correspond, avec le manifeste de la source, la version du descripteur et l'identifiant de liaison) : réponse 202 avec "duplicate": true et le receiptId d'origine, et écriture unique. L'identifiant est mémorisé une heure par défaut après l'écriture ou la mise de côté de la livraison (la durée est un réglage du déploiement) ; ensuite un renvoi est une nouvelle livraison.
• Même identifiant de livraison, alertes différentes : ne jamais l'envoyer. Le récepteur refuse le conflit en interne et l'émetteur voit 503 push_acceptance_unavailable, qui ressemble à une panne et se répétera tant que l'identifiant est réutilisé.
• Reprendre sur 429, 503 et les échecs réseau, avec le même identifiant de livraison et le même corps, un horodatage neuf et un délai croissant. Ne pas reprendre sur les autres 4xx sans corriger la cause.
• Les livraisons sont écrites dans l'ordre où elles ont été acceptées, une à la fois pour la source. Les lignes d'alerte sont écrites en upsert sur alertId : un renvoi tardif d'une alerte sous un nouvel identifiant de livraison réécrit la même ligne ; une annulation envoyée avant une alerte retardée serait écrasée par elle. Envoyez l'annulation après le 202 de l'alerte.

Correspondance avec le plan public de la SSA

Le plan public d'une alerte de sûreté du navire (chapitre XI-2, règle 6 de SOLAS ; Code ISPS) est le suivant : l'alerte identifie le navire, donne sa position et l'heure, et indique que la sûreté du navire est menacée ou compromise. Elle est envoyée à une autorité compétente à terre et non à d'autres navires. Correspondance avec le contrat :

Le contrat n'a pas de champ de cap, de vitesse, de type d'alerte ni de texte libre.

Où chaque règle est appliquée

Les chemins sont relatifs à la racine du dépôt ; chaque règle est désignée par le symbole qui la porte, car les numéros de ligne bougent.