Referencia de la API

Main GraphQL HTTP

Solicitudes cifradas para una sesión iniciada.

key = Base64Decode(session.token)Sesión autenticada; c-id = clientId

Cliente
https://<host>:<port>/graphql
Servidor

POST /graphql

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

HTTP · binary

JSON({ requestId, query, variables })

requestId es UUIDv7 y contiene la hora de solicitud. variables, operationName y extensions son opcionales.

Usar un requestId UUIDv7 nuevo para cada solicitud. Su hora debe estar a ±30 minutos de la del servidor. Los UUID se deduplican en memoria.

XChaCha20-Poly1305 · Pasar el cursor o tocar un campo
1 / 2

Protección contra repetición

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Autenticar y descifrarsession.token✕ → Rechazar
↓
Validar la hora de UUIDv7|serverTime − requestId timestamp| ≤ 30 min✕ → Rechazar
↓
Registrar requestId antes de ejecutarsession → request-ID set
✓ ↓Ejecutar GraphQL
✕ ↓Rechazar requestId reutilizados
Token de API Bearer: JSON por HTTPS, sin cifrado del cuerpo →
Llamadas a la biblioteca

Extractos de Desktop. graphqlRequestPayload crea un requestId UUIDv7. Cifra el JSON con AAD que vincula HTTP_REQUEST, POST y el destino lógico; después valida la vinculación de la respuesta.

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: falta una sesión autenticada o no es válida. La clave de sesión guardada sigue siendo válida después de reiniciar hasta que se revoque o se sustituya. 400: requestId mal formado, caducado o duplicado. 429: caché de protección contra repetición llena.