API 참조
게스트 GraphQL
공유 링크를 통한 암호화된 접근입니다.
key = Base64UrlDecode(shared_token)공유 링크의 shared_token; c-id = shareId
클라이언트
https://<host>:<port>/guest_graphql서버
POST /guest_graphql
c-id: 01a1cd7b-b900-7331-9331-313131313131
HTTP · binary
JSON({ requestId, query, variables })
requestId는 요청 시각을 포함하는 UUIDv7입니다. variables, operationName, extensions는 선택 사항입니다.
XChaCha20-Poly1305 · 필드에 마우스를 올리거나 탭하세요
재전송 공격 방지
requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption인증 및 복호화
↓shareId → shared_token✕ → 거부UUIDv7 시간 검증
↓|serverTime − requestId timestamp| ≤ 60 s✕ → 거부실행 전에 requestId 기록
SQLite: guest + shareId + requestId✓ ↓GraphQL 실행
✕ ↓재사용된 requestId 거부
라이브러리 호출
데스크톱 발췌입니다. 같은 graphqlRequestPayload 헬퍼가 UUIDv7 requestId를 생성하며 별도 타임스탬프나 재전송 방지 nonce는 보내지 않습니다.
typescript
// plain-desktop/src/lib/api/guest.ts
const payload = graphqlRequestPayload(query, variables)
const requestBody = chachaEncrypt(key, payload, httpRequestAad('/guest_graphql'))
const response = await httpRequest(url, {
method: 'POST', headers: { 'c-id': shareId }, 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 403: 비활성 공유 또는 비활성화된 원격 접근. 401: 복호화 실패. 400: 형식이 잘못되거나 만료 또는 중복된 요청.
타입 정의
graphql
scalar Instant
scalar Long
type Query {
sharedInfo(: String, : String): SharedInfo!
}
type SharedFile {
name: String!
relativePath: String!
isDir: Boolean!
size: Long!
mimeType: String!
hasThumb: Boolean!
createdAt: Instant
updatedAt: Instant!
}
type SharedInfo {
name: String!
readOnly: Boolean!
requiresPassword: Boolean!
expiresAt: Instant
urlToken: String!
entries: [SharedFile!]!
}
"""
Directs the executor to include this field or fragment only when the `if` argument is true.
"""
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
"""
Directs the executor to skip this field or fragment when the `if` argument is true.
"""
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
schema {
query: Query
}