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 거부
라이브러리 호출
데스크톱 발췌입니다. 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: 재전송 방지 캐시가 가득 찼습니다.