SDK et intégration

SDK @ayiid/sdk

Le SDK intégrateur « Vérifier avec AYIiD » : échange clé API vers jeton, création de demandes, statut, vérification des webhooks. Isomorphe, sans dépendance runtime.

Installation

1npm install @ayiid/sdk

Le SDK utilise l’API fetch globale (Node 18+ ou navigateur). Une implémentation de fetch peut être injectée (tests, runtimes anciens).

Initialisation

1import { AyiidClient } from '@ayiid/sdk';
2
3const ayiid = new AyiidClient({
4  apiKey: process.env.AYIID_API_KEY,
5  baseUrl: 'https://api.ayiid.example',
6  webBaseUrl: 'https://app.ayiid.example' // optionnel, defaut : baseUrl
7});

AyiidClientOptions

Champ	Type	Description
`apiKey`requis	string	Clé API du vérificateur (secrète, côté serveur).
`baseUrl`requis	string	Origine de l’API AYIiD.
`webBaseUrl`	string	Origine web pour l’URL hébergée de consentement. Défaut : baseUrl.
`fetch`	typeof fetch	Implémentation de fetch injectable (tests).

Gestion des jetons

Le client échange automatiquement la clé API contre un jeton d’accès, le met en cache et le renouvelle une fois sur réponse 401. Vous n’avez pas à gérer les jetons manuellement.

Méthodes

createVerification(input)

Crée une demande de vérification pour un sujet (DID). Renvoie { requestId, status }.

1const demande = await ayiid.createVerification({
2  subjectRef: 'did:ayi:z6Mkf...abcd',
3  scope: ['identity', 'is_adult'],
4  reason: 'Ouverture de compte',
5  mode: 'PROOF_ONLY',            // ou 'SELECTIVE'
6  callbackUrl: 'https://exemple.com/webhooks/ayiid',
7  requireLiveness: { minLevel: 'L2', maxAgeDays: 30 }
8});

Champ	Type	Description
`subjectRef`requis	string	DID du sujet.
`scope`requis	string[]	Attributs demandés.
`reason`requis	string	Motif lisible présenté au détenteur.
`mode`	PROOF_ONLY \| SELECTIVE	Mode de divulgation.
`callbackUrl`	string	URL de webhook.
`requireLiveness`	{ minLevel: L1\|L2\|L3, maxAgeDays? }	Exigence de preuve du vivant.

getVerification(requestId)

Consulte l’état d’une demande. Renvoie { requestId, status }.

1const etat = await ayiid.getVerification('req_9f3a...');

getAttestationStatus(attestationId)

Consulte le statut public d’une attestation. Renvoie { status } (VALID ou REVOKED).

1const { status } = await ayiid.getAttestationStatus('att_9f3a...');

hostedVerifyUrl(requestId)

Construit l’URL hébergée de consentement à présenter au détenteur.

1const url = ayiid.hostedVerifyUrl('req_9f3a...');
2// https://app.ayiid.example/verify/req_9f3a...

Gestion des erreurs

Tout appel en échec lève AyiidApiError, qui expose le statut HTTP (status), un message et le corps de réponse (body).

1import { AyiidApiError } from '@ayiid/sdk';
2
3try {
4  await ayiid.createVerification({ /* ... */ });
5} catch (err) {
6  if (err instanceof AyiidApiError) {
7    console.error(err.status, err.message, err.body);
8  }
9}

Le moteur signe le corps brut du webhook en HMAC-SHA256 avec le secret du vérificateur et pose la signature hexadécimale dans l’en-tête x-ayiid-signature(exporté comme SIGNATURE_HEADER). Vérifiez toujours la signature sur le corps brut, avant tout parsing JSON.

1import { verifyWebhookSignature, SIGNATURE_HEADER } from '@ayiid/sdk';
2
3const ok = verifyWebhookSignature(
4  process.env.AYIID_WEBHOOK_SECRET, // secret du verificateur
5  rawBody,                           // corps BRUT recu (chaine)
6  req.headers[SIGNATURE_HEADER]      // 'x-ayiid-signature'
7);
8if (!ok) throw new Error('signature invalide');

Champ	Type	Description
`SIGNATURE_HEADER`	const string	Nom de l’en-tête de signature : x-ayiid-signature.
`signWebhook(secret, body)`	string	Calcule la signature HMAC-SHA256 hexadécimale d’un corps (utilitaire, tests).
`verifyWebhookSignature(secret, body, signature)`	boolean	Vérifie la signature en temps constant. false si en-tête absente ou divergente.

Corps brut obligatoire

La vérification doit porter sur le corps exact reçu. Si votre framework parse le JSON automatiquement, conservez une copie du corps brut (par exemple via un rawBody) pour la signature.