Riferimento API

Main GraphQL HTTP

Richieste cifrate per una sessione autenticata.

key = Base64Decode(session.token)Sessione autenticata; c-id = clientId

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

POST /graphql

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

HTTP · binary

JSON({ requestId, query, variables })

requestId è UUIDv7 e contiene l’ora della richiesta. variables, operationName ed extensions sono facoltativi.

Usare un nuovo requestId UUIDv7 per ogni richiesta. La sua ora deve rientrare in ±30 minuti rispetto al server. Gli UUID vengono deduplicati in memoria.

XChaCha20-Poly1305 · Passare il puntatore o toccare un campo
1 / 2

Protezione dai replay

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Autenticare e decifraresession.token✕ → Rifiutare
↓
Verificare il timestamp UUIDv7|serverTime − requestId timestamp| ≤ 30 min✕ → Rifiutare
↓
Registrare requestId prima di eseguiresession → request-ID set
✓ ↓Eseguire GraphQL
✕ ↓Rifiutare requestId riutilizzati
Token API Bearer: JSON tramite HTTPS, senza cifratura del corpo →
Chiamate alla libreria

Estratti di Desktop. graphqlRequestPayload crea un requestId UUIDv7. Cifra il JSON con AAD che vincola HTTP_REQUEST, POST e l’endpoint logico, quindi verifica il vincolo della risposta.

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: sessione autenticata mancante o non valida. La chiave di sessione salvata resta valida dopo il riavvio finché non viene revocata o sostituita. 400: requestId malformato, scaduto o duplicato. 429: cache antireplay piena.