Référence de l'API

Main GraphQL HTTP

Requêtes chiffrées pour une session connectée.

key = Base64Decode(session.token)Session authentifiée ; c-id = clientId

Client
https://<host>:<port>/graphql
Serveur

POST /graphql

c-id: 706c6169-3b80-8f42-9a61-4e312e54d001

HTTP · binary

JSON({ requestId, query, variables })

requestId est un UUIDv7 et contient l’heure de la requête. variables, operationName et extensions sont facultatifs.

Utiliser un nouveau requestId UUIDv7 pour chaque requête. Son heure doit être à ±30 minutes de celle du serveur. Les UUID sont dédupliqués en mémoire.

XChaCha20-Poly1305 · Survoler ou toucher un champ
1 / 2

Protection anti-rejeu

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Authentifier et déchiffrersession.token✕ → Rejeter
↓
Vérifier la date UUIDv7|serverTime − requestId timestamp| ≤ 30 min✕ → Rejeter
↓
Enregistrer requestId avant exécutionsession → request-ID set
✓ ↓Exécuter GraphQL
✕ ↓Rejeter les requestId réutilisés
Jeton d’API Bearer : JSON via HTTPS, sans chiffrement du corps →
Appels de bibliothèque

Extraits de Desktop. graphqlRequestPayload crée un requestId UUIDv7. Chiffrez le JSON avec un AAD liant HTTP_REQUEST, POST et le point d’entrée logique, puis vérifiez la liaison de la réponse.

typescript
// plain-desktop/src/lib/api/gql-client.ts
const payload = graphqlRequestPayload(query, variables)
const requestBody = chachaEncrypt(key, payload, httpRequestAad('/graphql'))
const response = await httpRequest(url, {
  method: 'POST', headers: { 'c-id': clientId }, body: requestBody
})
if (!response.ok) throw new Error(String(response.status))
const bytes = new Uint8Array(await response.arrayBuffer())
const result = JSON.parse(decryptGraphqlResponse(key, requestBody, bytes))
// Feature error codes are carried in extensions.code; message is diagnostic text.
if (result.errors?.length) throw GqlError.fromGraphql(result.errors[0])

HTTP 401 : la session authentifiée manque ou n’est pas valide. Une clé de session enregistrée reste valide après un redémarrage, tant qu’elle n’a pas été révoquée ou remplacée. 400 : requestId mal formé, expiré ou déjà utilisé. 429 : cache anti-rejeu saturé.