fetch_certificate

Vue d’ensemble

fetch_certificate récupère l’URL du certificat eIDAS Certigna pour une contribution IP Secure scellée. Introduit en v1.4.2 (#415) pour combler un trou : Jinnove / Certigna génère le certificat eIDAS de manière asynchrone, donc le champ ipsecure_certificate_url retourné par seal_* est presque toujours null immédiatement.

Cet outil est idempotent et NULL-guardé côté ledger — vous pouvez le rappeler en boucle sans risque.

Note

Comportement attendu : appeler fetch_certificate(ledger_id) quelques minutes après un seal réel. Si le certificat n’est pas encore prêt, le tool retourne status: "pending" — vous pouvez réessayer plus tard.

Paramètres

Deux formes acceptées (au moins l’une doit être fournie) :

ledger_id number

Forme préférée. ID de l’entrée du ledger pour laquelle récupérer le certificat. Le tool résout automatiquement ipsecure_project_id et ipsecure_contribution_id depuis le ledger row.

{ "ledger_id": 42 }

ipsecure_project_id string

ID du projet IP Secure (forme directe, requise quand ledger_id est omis).

{ "ipsecure_project_id": "abc123", "contribution_id": "mwMWTpjmu3" }

contribution_id string

ID de la contribution IP Secure (forme directe, requise quand ledger_id est omis).

Statuts retournés

Status	Signification
ready	URL fraîchement récupérée chez Jinnove et persistée dans le ledger.
already_persisted	L’URL était déjà stockée dans le ledger — aucun appel API effectué.
pending	Jinnove n’a pas encore généré le certificat. Réessayer dans quelques minutes.
not_configured	IP Secure n’est pas configuré, OU le ledger row n’a pas de ipsecure_contribution_id (seal local uniquement).

Réponse

ready

{
  "status": "ready",
  "ledger_id": 42,
  "contribution_id": "mwMWTpjmu3",
  "certificate_url": "https://certigna.fr/cert/abc-123.pdf",
  "hint": "Certificate fetched and persisted."
}

already_persisted

{
  "status": "already_persisted",
  "ledger_id": 42,
  "contribution_id": "mwMWTpjmu3",
  "certificate_url": "https://certigna.fr/cert/abc-123.pdf",
  "hint": "Certificate URL was already stored in the ledger — no API call performed."
}

pending

{
  "status": "pending",
  "ledger_id": 42,
  "contribution_id": "mwMWTpjmu3",
  "certificate_url": null,
  "hint": "Jinnove has not generated the eIDAS certificate yet. Retry in a few minutes."
}

not_configured

{
  "status": "not_configured",
  "ledger_id": 42,
  "contribution_id": null,
  "certificate_url": null,
  "hint": "Ledger entry 42 has no IP Secure contribution_id (local-only seal)"
}

Workflow recommandé

1. Sceller la preuve

   Scelle le fichier rapport.pdf pour mon projet — asset_types ["programme_rnd"]

   Sortie typique :

   {
     "ipsecure_contribution_id": "mwMWTpjmu3",
     "ipsecure_certificate_url": null,  // ← async, normal
     "fingerprint": "476b712a..."
   }

2. Attendre 1 à 5 minutes (le temps que Certigna génère le certificat)

3. Récupérer le certificat

   Récupère le certificat pour l'entrée 42

   fetch_certificate({ "ledger_id": 42 })

4. Si status: "pending", réessayer

   Pas d’erreur — c’est le comportement attendu. Patience.

Bonnes pratiques

Astuce

Polling agent : un workflow agent solide est de boucler fetch_certificate toutes les 2 min sur les entrées récentes dont ipsecure_certificate_url IS NULL. C’est exactement ce que ferait un job cron — l’agent peut le faire à la demande.

Attention

Ne pas confondre pending et not_configured : pending signifie “Jinnove travaille dessus, réessaie”, tandis que not_configured signifie “ce seal n’a jamais touché Jinnove” (typiquement un seal local sans IP Secure activé). Inutile de boucler sur not_configured.

Détails d’implémentation

• L’écriture dans le ledger utilise updateLedgerIpSecureCertificate() qui est NULL-guardé : si une URL existe déjà (race condition), elle n’est pas écrasée.
• L’appel à Jinnove passe par IpSecureClient.getCertificate() qui utilise le rate-limiter.ts + circuit-breaker.ts standard du projet — donc résilient aux pannes Jinnove (3-state circuit : closed → open → half_open).
• L’outil est sans effet de bord destructif : il ne supprime jamais, n’overrride jamais. Vous pouvez l’appeler en boucle.

Voir aussi

• seal_file — scelle un fichier (génère un contribution_id)
• seal_content — scelle du contenu inline
• seal — scelle un artefact git
• Concepts → Attestations — comment le certificat eIDAS s’intègre au faisceau d’indices