PlainApp
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 · 悬停或点按字段
1 / 2

防重放

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
认证并解密session.token✕ → 拒绝
↓
校验 UUIDv7 时间|serverTime − requestId timestamp| ≤ 30 min✕ → 拒绝
↓
执行前记录 requestIdsession → request-ID set
✓ ↓执行 GraphQL
✕ ↓拒绝重复的 requestId
Bearer API Token:HTTPS JSON,不做请求体加密 →
库调用示例

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:防重放缓存已满。