API 參考
Main GraphQL HTTP
登入工作階段的加密請求。
key = Base64Decode(session.token)已登入工作階段;c-id = clientId
用戶端
https://<host>:<port>/graphql伺服器
POST /graphql
c-id: 706c6169-3b80-8f42-9a61-4e312e54d001
HTTP · binary
JSON({ requestId, query, variables })
requestId 為 UUIDv7,內含請求時間;variables、operationName、extensions 可選。
每次使用新的 UUIDv7 requestId,時間在伺服器 ±30 分鐘內。按 UUID 值在記憶體中去重。
XChaCha20-Poly1305 · 將游標移至欄位或點按
防重放
requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption驗證並解密
↓session.token✕ → 拒絕檢查 UUIDv7 時間
↓|serverTime − requestId timestamp| ≤ 30 min✕ → 拒絕執行前記錄 requestId
session → request-ID set✓ ↓執行 GraphQL
✕ ↓拒絕重複的 requestId
函式庫呼叫範例
Desktop 程式碼節錄。graphqlRequestPayload 產生 UUIDv7 requestId;以綁定 HTTP_REQUEST、POST 與邏輯端點的 AAD 加密 JSON,再驗證回應的綁定。
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:工作階段不存在或無效。已儲存的工作階段金鑰在重新啟動後仍有效,直到工作階段撤銷或金鑰被替換。HTTP 400:requestId 格式錯誤、過期或重複。HTTP 429:防重放快取已滿。