Origines autorisées

La Réception expose deux clés très différentes. La clé secrète cof_ reste sur votre serveur et ne quitte jamais votre infrastructure. La clé publiable cip_, elle, est conçue pour vivre dans le navigateur de vos visiteurs : elle est visible dans le code source de votre page. C'est volontaire, mais cela impose un garde-fou. Le champ allowed_origins restreint les domaines depuis lesquels un dépôt est accepté, et metadata_policy contrôle les métadonnées que Coffrify conserve en clair. Ce document explique comment configurer ces deux réglages et comment sécuriser proprement votre intégration front.

Déclarer les origines à la création

Vous fournissez allowed_origins lorsque vous créez la réception. C'est un tableau d'origines au format schéma://hôte[:port]. La réponse renvoie la clé publiable cip_ (montrée une seule fois) ainsi que la liste d'origines normalisée.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const intake = await coffrify.intakes.create({
  name: 'Pièces justificatives',
  allowed_origins: [
    'https://app.exemple.fr',
    'https://www.exemple.fr',
  ],
  metadata_policy: 'envelope',
  reference_required: true,
});
 
// La clé publiable n'est renvoyée qu'ici, une seule fois.
console.log(intake.publishable_key); // cip_live_...
console.log(intake.allowed_origins); // origines normalisées

À chaque appel du navigateur, Coffrify lit l'en-tête Origin envoyé par le navigateur et le compare à votre liste. Si l'origine ne correspond pas, la requête est refusée et la réponse ne porte aucun en-tête CORS permissif : le navigateur masque alors le résultat à la page appelante. Votre clé devient inutilisable hors de vos domaines, même si quelqu'un la recopie.

Comment les origines sont comparées

La comparaison se fait sur l'origine normalisée, c'est à dire schéma://hôte[:port]. L'hôte est mis en minuscules, et tout chemin, paramètre ou fragment que vous laisseriez dans la valeur est ignoré. La correspondance est exacte : il n'y a pas de joker de sous domaine. Déclarez donc chaque hôte que vous utilisez réellement.

Maîtriser les métadonnées avec metadata_policy

metadata_policy décide de ce que Coffrify conserve en clair à côté d'un dépôt. Deux valeurs sont possibles.

Resserrer une clé publiable

Une clé publiable peut porter sa propre liste d'origines, plus étroite que celle de la réception. Quand c'est le cas, les deux listes doivent valider la requête : l'origine doit appartenir à celle de la réception et à celle de la clé. C'est utile pour émettre des clés distinctes par site ou par environnement tout en conservant une réception unique. Par exemple, une réception ouverte à app.exemple.fr et staging.exemple.fr, avec une clé de production restreinte au seul app.exemple.fr.

Vérifier la configuration

La lecture d'une réception renvoie allowed_origins, metadata_policy et reference_required tels qu'ils sont appliqués. Contrôlez ces champs après chaque modification.

$ cof intakes get intk_123 --json | jq '{allowed_origins, metadata_policy, reference_required}'
{
  "allowed_origins": [
    "https://app.exemple.fr",
    "https://www.exemple.fr"
  ],
  "metadata_policy": "envelope",
  "reference_required": true
}

Bonnes pratiques côté front

• Listez toutes vos origines réelles : domaine principal, sous domaines (app, www), et l'origine exacte de préproduction. La correspondance étant exacte, un hôte oublié bloque les dépôts.
• Servez vos pages en HTTPS et déclarez l'origine en https://. Réservez http://localhost au développement, sur une clé de test.
• Une clé par environnement : cip_test_ ou cip_sandbox_ pour le développement, cip_live_ en production. Ne réutilisez jamais une clé de test en prod.
• N'utilisez jamais la clé secrète `cof_` dans le navigateur. Seule la clé publiable cip_ est prévue pour le front ; la clé secrète reste sur votre serveur.
• **Évitez le joker * en production** : il neutralise la protection d'origine.
• Gardez les métadonnées d'enveloppe non sensibles : références opaques uniquement, jamais de secret ni d'identité directe.