API v1
Basis: https://eclair.kayzen-lyon.com/api/v1. Überall JSON, Antworten werden nie zwischengespeichert. Binärdaten sind base64url ohne Padding. openapi.json
Goldene Regel: Verschlüsseln Sie, bevor Sie die API aufrufen. Senden Sie nie den Link-Schlüssel, die PIN oder Klartext. Am einfachsten nutzen Sie unseren JavaScript-Client (Paket api-client) oder die CLI.
Routen
| Methode | Route | Zweck |
|---|---|---|
POST | /secrets | Stocker un secret déjà chiffré |
POST | /secrets/{id}/preview | Libellé chiffré et indicateurs, sans le contenu |
POST | /secrets/{id}/reveal | Révéler (consomme une lecture) |
GET | /manage/{id} | Statut et historique (accusé de lecture) |
DELETE | /manage/{id} | Détruire avant lecture |
POST | /uploads | Ouvrir un envoi de fichiers chiffrés |
POST | /uploads/{id}/parts | URL présignée (5 min) pour une partie |
POST | /requests | Créer une demande de secret (lien de dépôt) |
POST | /requests/{id}/deposits | Déposer un contenu chiffré pour le demandeur |
GET | /requests/{id}/deposits | Lister les dépôts (demandeur) ou vérifier que le lien est ouvert (sans jeton) |
DELETE | /requests/{id} | Fermer la demande et supprimer les dépôts |
POST | /abuse | Signaler un lien abusif |
POST | /webhooks | Enregistrer un webhook https |
DELETE | /webhooks/{id} | Supprimer un webhook |
POST | /domains | Réserver un domaine personnalisé |
GET | /domains/{domain} | État d'un domaine |
POST | /domains/{domain} | Vérifier l'enregistrement TXT et rattacher le domaine |
DELETE | /domains/{domain} | Libérer le domaine |
GET | /config | Limites de l'instance |
GET | /health | Santé du service |
Beispiel (TypeScript, lokale Verschlüsselung)
import { sendSecret, parseSecretLink, receiveSecret } from "@sesame-eclair/api-client";
const options = { baseUrl: "https://eclair.kayzen-lyon.com" };
// Encrypts in this process, then uploads only the ciphertext.
const sent = await sendSecret(options, {
content: { v: 1, type: "text", text: "DB_PASSWORD=..." },
views: 1,
ttlSeconds: 3600,
});
if (sent.ok) console.log(sent.url, sent.manageUrl);
// Recipient side: the key comes from the link fragment.
const link = parseSecretLink(sent.ok ? sent.url : "")!;
const received = await receiveSecret(options, link);Statuscodes
404— dieselbe Antwort für unbekannte, abgelaufene, bereits gelesene oder vernichtete Secrets.401— falsche PIN, mit attemptsLeft.403— access_denied: Netzwerk oder Land des Lesers erfüllen die Beschränkungen des Secrets nicht. Das Secret bleibt unversehrt.423— noch nicht lesbar (verzögerte Freigabe), mit availableAt.429— zu viele Anfragen, erneut versuchen in einer Stunde.
Webhooks
Registrieren Sie eine https-URL mit POST /webhooks und übergeben Sie dann webhookId beim Erstellen des Secrets. Sie erhalten { event, secretId, at } für created, revealed, burned, revoked und expired: nie den Inhalt. Das signingSecret wird einmal angezeigt; prüfen Sie jeden Aufruf so:
import { createHmac, timingSafeEqual } from "node:crypto";
// header = request.headers["eclair-signature"], body = raw request body (string)
function verify(header: string, body: string, signingSecret: string): boolean {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
const expected = createHmac("sha256", Buffer.from(signingSecret, "base64url"))
.update(`${t}.${body}`)
.digest();
return timingSafeEqual(expected, Buffer.from(v1, "hex"));
}Zugriffsbeschränkungen
accessRules: { cidrs: ["203.0.113.0/24"], countries: ["FR"] } beschränkt das Öffnen auf Netzwerke oder Länder (jeweils höchstens 20 Einträge). Die Prüfung erfolgt, bevor verschlüsselte Daten gesendet werden; ein unbekanntes Land wird abgelehnt, sobald eine Länderregel existiert.
Eigene Domain
POST /domains beansprucht eine Domain und gibt einen TXT-Verifizierungseintrag und einen CNAME zurück. Danach prüft POST /domains/{domain} den TXT-Eintrag und verknüpft die Domain; das TLS-Zertifikat wird automatisch ausgestellt. Die Seite „Eigene Domain“ erledigt all das für Sie.