Documentation SDK — ELYSÉA CERVEAU

La documentation technique du SDK.
Tout ce qu'il faut pour intégrer, rien de plus.

Authentification, API surface, 8 prohibitions Guardian, paliers, trust mark, sandbox et codes d'erreur. Canons figés — aucun contenu généré par IA.

Quickstart Télécharger la doc (PDF)SDK & Tarifs

§1 — Authentification

Clé de test sk_test_

Sandbox uniquement. Aucune donnée utilisateur réelle. Aucune facturation UAM. Toutes les prohibitions Guardian sont actives (le sandbox est un test de conformité, pas un mode permissif).

Clé de production sk_live_

Production uniquement. Facturation UAM active (token LLM à la charge du constructeur — Décision KJ). Mélanger sk_test_ en production ou sk_live_ en sandbox lève immédiatement ELYSEA_INIT_ERROR.

typescript

import { createElyseaClient } from '@elysea/core';

const elysea = createElyseaClient({
  baseUrl:     process.env.ELYSEA_BASE_URL!,
  auth: { apiKey: process.env.ELYSEA_API_KEY!, apiSecret: process.env.ELYSEA_API_SECRET! },
  appId:       process.env.ELYSEA_APP_ID!,
  countryCode: 'FR',
  region:      'EU',
});

Le champ regionest obligatoire. ELYSÉA opère exclusivement en EU — aucun fallback vers des régions hors-UE n'est disponible.

§2 — API surface

identity.resolve()

typescript

const { coreUserId } = await elysea.identity.resolve({
  userJwt: req.headers.authorization, // JWT émis par votre auth provider
});
// coreUserId : identifiant opaque dérivé de l'ELYSEAID
// Jamais le pseudonyme réel — jamais l'identité sous-jacente

pipeline.run()

typescript

const result = await elysea.pipeline.run({
  userInput:           message,
  coreUserId,
  conversationHistory: history,   // Message[] — { role, content }[]
});

// result : PipelineResult
// {
//   response:         string,    // réponse texte
//   posture:          string,    // posture Guardian active
//   guardianAction:   string,    // 'pass'|'warn'|'block'
//   canonConformance: boolean,   // true si conforme aux canons
//   errorCode?:       string,    // si guardianAction === 'block'
//   errorMessage?:    string,    // si guardianAction === 'block'
// }

memory.write()

typescript

await elysea.memory.write({
  coreUserId,
  type:     'context',         // l'un des 5 types autorisés (FIGÉ)
  content:  'Travaille en UTC+2, équipe distribuée.',  // ≤ 256 caractères
  ttlDays:  90,                // TTL obligatoire — pas de persistance infinie
  scope:    'your-app-id',     // scopé à votre app uniquement
});
// Requiert le consentement scopé actif de l'utilisateur (P7 sinon)

guardian.audit()

typescript

const log = await elysea.guardian.audit({
  coreUserId,
  event: 'session_close',
});
// Retourne le GuardianLog de la session
// Utile pour la conformité et le débogage — lecture seule

ELYSEA.ARCH.CANON_GUARDIAN_SDK.v1 — FIGÉ

§3 — 8 prohibitions

Un tiers peut RESTREINDRE — jamais affaiblir.

Vous pouvez configurer ELYSÉA pour être plus strict que la baseline (bloquer des sujets, réduire les types de mémoire utilisés, exiger un consentement plus fin). Vous ne pouvez pas configurer ELYSÉA pour être moins protecteur. Le Guardian SDK rejette toute configuration qui affaiblirait une prohibition existante — par architecture, pas par politique.

Comportement de bloc : le Guardian ne retourne jamais HTTP 403. Il retourne une réponse pipeline normale — guardianAction: “block”, posture: “present_neutral”. L'utilisateur ne sait pas qu'une tentative de contournement a eu lieu. Le log interne, lui, le sait.

P1BLOC immédiat

Contourner ou modifier D0

Toute tentative de remplacer, neutraliser ou court-circuiter la directive éthique socle (D0). D0 ne peut être restreinte — jamais affaiblie.

signal: P1_D0_OVERRIDE_ATTEMPT

P2BLOC immédiat

Accéder à la mémoire brute

Lecture directe des items mémoire d'un utilisateur sans passer par le pipeline de résolution consentie. Aucun endpoint SDK n'existe pour ça.

signal: P2_MEMORY_RAW_ACCESS

P3BLOC immédiat

Bypass de la safety gate

Toute requête conçue pour contourner les garde-fous (jailbreak de prompt, injection système, wrapping LLM externe non signé).

signal: P3_SAFETY_GATE_BYPASS_ATTEMPT

P4WARN

LLM sans signature conforme

Appel pipeline vers un modèle LLM ne présentant pas de watermark ELYSÉA valide. Loggé — escalade si récurrent.

signal: P4_NON_CONFORM_LLM_SIGNATURE

P5BLOC

Watermark absent dans la sortie

Réponse pipeline renvoyée sans métadonnée de traçabilité ELYSÉA. La chaîne de conformité est rompue.

signal: P5_WATERMARK_MISSING

P6BLOC immédiat

Croisement cross-constructeur sans consentement

Exploitation des données mémoire issues d'une autre app de l'écosystème sans consentement scopé actif de l'utilisateur.

signal: P6_CROSS_BUILDER_CONSENT_MISSING

P7BLOC

Appel sans token de consentement

Requête pipeline ou memory.write lancée sans fournir le token de consentement ELYSÉA valide pour l'utilisateur concerné.

signal: P7_MISSING_CONSENT_TOKEN

P8WARN → RÉVOCATION

Badge non vérifié affiché

Affichage d'un trust mark ELYSÉA (Powered by / Vérifié — mesures publiques) sans validation active. Warn d'abord — révocation immédiate si fraude confirmée.

signal: P8_UNCERTIFIED_BADGE_USAGE

Source : ELYSEA.ARCH.CANON_GUARDIAN_SDK.v1 §3 — ELYSEA.SDK.INTEGRITY_PROTECTION.v1 §4. Ce canon est figé — ELYSÉA ne peut pas retirer une prohibition par décision commerciale.

§4 — Paliers & accès

Palier	Prix	Clé	Environnement	Quota	Badge
TEST	Gratuit	`sk_test_`	Sandbox · sans limite de durée · volume plafonné	1 app · communautaire	Powered by ELYSÉA
VOTRE PRODUIT	À partir de 2,50 €	`sk_live_`	Production · par utilisateur actif dans le mois	Dégressif : 2,50 / 1,50 / 0,80 €	Powered by ELYSÉA
VOS ÉQUIPES Enterprise · Plateformes · Public · Éducation : sur demande	À partir de 30 €/an	`sk_live_`	Production · par employé couvert	Licence annuelle · rapport conformité inclus	Powered by ELYSÉA

BYOK obligatoire — les tokens LLM sont toujours à la charge du constructeur. TEST gratuit sans limite de durée. VOTRE PRODUIT dégressif dès le premier utilisateur actif. VOS ÉQUIPES licence annuelle par employé couvert. Enterprise et cas spéciaux sur demande. Détail complet : page tarifs.

§5 — Trust mark & badges

Discovery et supérieur

Badge de premier niveau. Indique que l'app intègre le SDK ELYSÉA avec les 8 prohibitions actives. Vérifiable par l'utilisateur via son portail ID.

Vérifié — mesures publiques

Mesure sur corpus scellés

Niveau supérieur. Attribué après procédure de mesure sur états précis du pipeline — résultats versionnés et publiés à l'issue de la campagne. Ce niveau n'est pas encore émis (campagne en cours). Processus distinct de l'abonnement.

Révocation

Révocation immédiate

P1, P2, P3 (tentative active de contournement) et P8 (fraude de badge confirmée). Aucun délai de grâce.

Délai de 10 jours

P4, P5, P6, P7 — infractions non-frauduleuses. Le constructeur reçoit une notification et dispose de 10 jours pour corriger avant révocation.

Appel — 15 jours

Toute révocation peut être contestée dans un délai de 15 jours calendaires suivant la notification. Procédure décrite dans le contrat partenaire.

Source : ELYSEA.SDK.TRUST_MARK.v1 §3, §5. Voir aussi : page Trust mark.

trust.verify() — vérification programmatique

Le namespace trustdu SDK permet de vérifier le statut de vérification d’une app et de valider l’authenticité d’une attestation HMAC côté Core. Usage typique : afficher le badge correct à l’utilisateur, ou auditer un partenaire tiers.

trust.fetchAttestation(appId)

→ Promise<TrustMarkAttestation | null>

Récupère l'attestation trust mark depuis le Core pour un appId donné. Retourne null si le Core est inaccessible ou l'appId inconnu.

trust.getStatus(attestation)

→ CertificationStatus

Dérive le statut de vérification depuis une attestation. Fonction pure — aucun appel réseau. Résultat : 'powered_by' | 'certified_ethical' | 'none'.

trust.verify(attestation)

→ Promise<{ valid: boolean }>

Vérifie l'attestationToken HMAC auprès du Core (POST /verify/attestation). Le Core contrôle la signature côté serveur. Retourne { valid: false } sur tout échec — aucune exception levée.

typescript

// Vérifier le trust mark d'une app partenaire
const attestation = await elysea.trust.fetchAttestation('app_a40a8bd4-008c-4ef4-aef7-b9666d6846a8');

if (!attestation) {
  // App inconnue ou Core inaccessible
  return { certified: false };
}

const status = elysea.trust.getStatus(attestation);
// status → 'powered_by' | 'certified_ethical' | 'none'

const { valid } = await elysea.trust.verify(attestation);
// valid → true si le HMAC est confirmé côté Core
// valid → false si le token est invalide, expiré, ou falsifié

ELYSEA.SDK.SANDBOX_PARTNER.v1 — FIGÉ

§6 — Sandbox — 5 invariants

I-SB-1

firm_safety toujours actif

Le mode de sécurité principal ne peut pas être désactivé en sandbox. Toute tentative de passer firm_safety: false est ignorée silencieusement.

I-SB-2

D0 active sans exception

La directive éthique socle (D0) est active en sandbox exactement comme en production. Le comportement Guardian est identique.

I-SB-3

Guardian SDK actif

Tous les blocs Guardian sont fonctionnels en sk_test_. Le sandbox est un vrai test de conformité — pas un bac à sable permissif.

I-SB-4

8 prohibitions actives

P1 à P8 sont intégralement appliquées. Les signaux d'erreur retournés sont identiques à la production.

I-SB-5

Garantie K intacte

La mémoire sacrée de l'utilisateur (items marqués K) est inaccessible en sandbox comme en production. Aucun endpoint de test ne contourne cette règle.

Erreur de mismatch environnement

typescript

// Erreur si clé sk_test_ utilisée en production (et vice versa)
// Vérifiez que ELYSEA_API_KEY correspond à l'environnement cible

try {
  const elysea = createElyseaClient({
    baseUrl:     'https://core.elysea.eu',
    auth: { apiKey: 'sk_test_abc123', apiSecret: 'secret' },
    appId:       'my-app',
    countryCode: 'FR',
    region:      'EU',
  });
} catch (err) {
  // err.code === 'ELYSEA_INIT_ERROR'
}

§7 — Codes d'erreur

Code	Type	Cause	Action recommandée
`ELYSEA_INIT_ERROR`	Config	Paramètres d'initialisation invalides (baseUrl, auth, appId…)	Vérifier la config createElyseaClient({ baseUrl, auth, appId, countryCode })
`P1_D0_OVERRIDE_ATTEMPT`	Guardian BLOC	Tentative de bypass D0	Violation P1 — révision architecture requise
`P2_MEMORY_RAW_ACCESS`	Guardian BLOC	Lecture directe mémoire utilisateur	Utiliser uniquement le pipeline de résolution consentie
`P3_SAFETY_GATE_BYPASS_ATTEMPT`	Guardian BLOC	Contournement safety gate détecté	Revue complète du prompt et de l'architecture LLM
`P4_NON_CONFORM_LLM_SIGNATURE`	Guardian WARN	LLM sans watermark ELYSÉA	Utiliser uniquement les modèles approuvés par ELYSÉA
`P5_WATERMARK_MISSING`	Guardian BLOC	Réponse pipeline sans métadonnée de traçabilité	Vérifier l'intégration — ne pas modifier la réponse pipeline brute
`P6_CROSS_BUILDER_CONSENT_MISSING`	Guardian BLOC	Croisement mémoire inter-app sans consentement scopé	Vérifier le token de consentement cross-app actif
`P7_MISSING_CONSENT_TOKEN`	Guardian BLOC	Appel sans token de consentement ELYSÉA valide	Recueillir le consentement utilisateur avant tout appel
`P8_UNCERTIFIED_BADGE_USAGE`	Guardian WARN	Badge affiché sans validation active	Retirer le badge

Les blocs Guardian ne génèrent pas de HTTP 4xx. La réponse est toujours un PipelineResult valide avec guardianAction: “block” et posture: “present_neutral”.

Une question sur la conformité ? Un cas limite non documenté ?

Parler à l'équipe Télécharger la doc (PDF)Quickstart dev

La documentation technique du SDK.Tout ce qu'il faut pour intégrer, rien de plus.