스펙들 3
탐색 1.0.1 문서
버전
문서 변경 이력
섹션 10
현재 페이지 7
1.0.1 ko public

스펙

RAWP

Current RAWP specification.

변경 이력 전체 Markdown 목차 Markdown

3. Phase 1: 등록, 페어링 및 키 교환 (Registration & Lifecycle)

클라이언트와 마스터 서버가 상호 통신을 위한 토큰 페어(Access/Refresh)를 교환하고 검증하는 단계다.

3.1. 페어링 URL 발급 (Master Server)

  • 형식: https://{master_host}/v1/auth/pair?token={pairing_token}
  • 제약 조건: pairing_token은 발급 후 15분 이내에 사용되지 않으면 반드시 폐기되어야 한다 (MUST).

3.2. 등록 주소 검증 규약 (Address Validation)

클라이언트가 제출하는 client_address에 대한 마스터 서버의 검증 규칙:

  • Allowed Schemes: https:// 사용 강제 (단, 명시적인 개발 플래그 활성화 시 http:// 허용).
  • Loopback Forbidden: 127.0.0.1, localhost 등 루프백 및 링크 로컬 주소는 등록을 거부해야 한다 (MUST).
  • Private Network: 192.168.x.x 등 사설 IP는 허용된다.

3.3. 등록 요청 및 상호 키 교환 (Mutual Registration)

클라이언트는 등록 시 자신이 마스터 서버를 호출할 때 쓸 토큰을 발급받음과 동시에, 마스터 서버가 자신을 호출할 때 사용할 초기 토큰 페어를 생성하여 전달해야 한다 (MUST).

Endpoint: POST /v1/auth/pair (Master Server 제공)

Request (Client → Master):

{
  "pairing_token": "String (필수, 최소 32자 이상)",
  "client_address": "String (필수, 향후 마스터가 호출할 URI)",
  "device_name": "String (필수, 최대 100자)",
  "client_credentials": {
    "access_token": "String (필수, 마스터가 클라이언트를 호출할 때 사용할 토큰)",
    "refresh_token": "String (필수, 클라이언트용 갱신 토큰)",
    "expires_in": "Number (필수, 초 단위)"
  }
}

Response (Master → Client) (200 OK):

{
  "access_token": "String (필수, 클라이언트가 마스터를 호출할 때 사용할 Bearer 토큰)",
  "refresh_token": "String (필수, 마스터용 장기 갱신 토큰)",
  "expires_in": "Number (필수)",
  "server_credentials": "Object (필수, 서버 서명 및 자격 증명용 JWK 공개키)"
}

3.4. 토큰 갱신 엔드포인트 대칭 구현 (Token Refresh)

양측은 타 API 호출 시 401 Unauthorized를 받으면, 발급 주체의 갱신 엔드포인트를 호출하여 토큰을 갱신하고 원래 요청을 재시도해야 한다 (MUST).

3.4.1. 클라이언트의 마스터 토큰 갱신 (Client → Master)

  • Endpoint: POST /v1/auth/refresh (Master Server 제공)
  • Request: {"refresh_token": "String (필수)"}
  • Response: §3.3의 Master → Client 응답 포맷과 동일.

3.4.2. 마스터의 클라이언트 토큰 갱신 (Master → Client)

  • Endpoint: POST /v1/auth/refresh (Local Client 제공)
  • Request: {"refresh_token": "String (필수)"}
  • Response:
{
  "access_token": "String (필수)",
  "refresh_token": "String (필수)",
  "expires_in": "Number (필수)"
}

3.5. 등록 해제 (Unregister)

클라이언트가 자발적으로 네트워크에서 이탈할 때 잔여 리소스를 정리한다.

  • Endpoint: DELETE /v1/nodes/self (Master Server 제공)
  • Headers: Authorization: Bearer {client_access_token}
  • 제약 조건: 마스터 서버는 해당 클라이언트와 연결된 모든 WSS 세션을 즉시 강제 종료하고 상태를 정리해야 한다 (MUST). 관련된 모든 토큰은 즉시 무효화된다.
  • Response: 204 No Content

참조