RAWP 1.0.2

1.0.2 ko public

변경 이력 전체 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.4.3. 토큰 갱신 상세 규칙

Refresh Token Rotation: 토큰 갱신 응답에는 항상 새로운 refresh_token이 포함되어야 한다 (MUST). 갱신에 사용된 기존 refresh_token은 즉시 무효화해야 한다 (MUST). 이를 통해 탈취된 토큰의 재사용을 방지한다.

Replay 감지: 이미 사용(무효화)된 refresh_token으로 갱신이 시도되면, 토큰 발급 주체는 해당 클라이언트(또는 사용자)에게 발급된 모든 토큰(access + refresh)을 즉시 무효화해야 한다 (MUST). 이는 토큰 탈취 후 공격자와 정당한 사용자가 경쟁적으로 갱신하는 시나리오를 차단한다. 무효화 후 401 Unauthorized를 반환한다.

갱신 실패 복구: refresh_token 자체가 만료되었거나 무효화되어 갱신이 불가능한 경우(401 Unauthorized 수신), 클라이언트는 재페어링(§3.3) 절차를 개시해야 한다 (MUST).

3.4.4. Edge → Master 토큰 관리

엣지 노드(§9)가 마스터 서버에 접속할 때 사용하는 사용자 토큰의 갱신 및 폐기 절차이다.

토큰 갱신 — Endpoint: POST /v1/edge/auth/refresh (Master Server 제공)

Request: {"refresh_token": "String (필수)"}

Response (200 OK):

{
  "access_token": "String (필수)",
  "refresh_token": "String (필수, 새로 발급된 토큰)",
  "expires_in": "Number (필수, 초 단위)"
}

§3.4.3의 Refresh Token Rotation 및 Replay 감지 규칙이 동일하게 적용된다 (MUST).

토큰 폐기 (로그아웃) — Endpoint: POST /v1/edge/auth/revoke (Master Server 제공)