PlainApp
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 · 필드에 마우스를 올리거나 탭하세요
1 / 2

재전송 공격 방지

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /guest_graphql
인증 및 복호화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(relativePath: String, password: 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
}