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✕ → 拒否
↓
実行前に requestId を記録session → request-ID set
✓ ↓GraphQL を実行
✕ ↓使用済み requestId を拒否
Bearer API Token:本文を暗号化しない HTTPS 上の JSON →
ライブラリ呼び出し

デスクトップ版からの抜粋です。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: 認証済みセッションがないか無効です。保存済みの鍵は再起動後も有効で、取り消しまたは置き換えまで使用できます。400: requestId が不正、期限切れ、または重複しています。429: リプレイキャッシュが満杯です。