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

스펙

RAWP

Current RAWP specification.

변경 이력 전체 Markdown 목차 Markdown

7. 보안 및 예외 처리 (Security & Errors)

7.1. HTTP 에러 응답 표준 규격

클라이언트나 서버가 HTTP 오류를 반환할 때, 다음 JSON 포맷을 Body에 포함해야 한다 (MUST).

{
  "error_code": "String (e.g., TOKEN_EXPIRED, SESSION_NOT_FOUND, INVALID_PATH)",
  "message": "String (휴먼 리더블 디버깅 메시지)"
}

상태 코드 매핑 규칙:

HTTP 상태 코드 사유
400 Bad Request 필수 파라미터 누락, 잘못된 UUID 포맷.
401 Unauthorized 토큰 만료, 서명 불일치, WSS Upgrade 티켓 무효.
403 Forbidden White-list 없는 명령어, 인가되지 않은 디렉토리 접근.
404 Not Found 존재하지 않는 session_id 제어 시도.
409 Conflict 이미 RUNNING 중인 세션에 reattach: false로 초기화 시도. Config Scope의 config_version 역전 감지 (§4.1.4).
422 Unprocessable Entity 설정 갱신 시 필드값 형식, 범위, 상호 정합성 위반 (§4.1.7).
429 Too Many Requests rate_limit 초과.
500 Internal Server Error 내부 파일 시스템 오류, 바인딩 충돌 등.
503 Service Unavailable 초기 설정 동기화 미완료 상태에서 세션 초기화 시도 (§4.1.2).

7.2. 보안 제약 및 필수 보호 장치 (MUST)

  • 경로 검증 (Path Normalization): 클라이언트는 모든 파일/디렉토리 조회 요청 시 경로 내 ../ 등을 정규화하고 인가된 workspace_path 범위 내인지 반드시 검증해야 한다 (Directory Traversal 방어).
  • 명령어 및 에이전트 보호 (Whitelisting): 활성화된 agent_name에 매핑된 명령어만 실행 가능해야 하며, 임의의 쉘 스크립트나 바이너리를 원격으로 주입받아 실행하는 시도는 차단해야 한다 (RCE 방어).
  • 버퍼 관리 및 OOM 방어: WSS 단절 중 자식 프로세스를 유지할 때 발생하는 출력은 버퍼에 저장하되, max_buffer_size에 도달하면 반드시 사전에 합의된 buffer_overflow_policy(RING/DROP)에 따라 강제로 메모리를 관리하여 게이트웨이 다운을 방지해야 한다.
  • 도구 호출 보안: RAWP-DPS 1.0.1 적용 시, tool.catalog.publish에서 고지된 도구만 tool.invoke.request에 사용 가능하며, 고지되지 않은 도구의 호출 요청은 클라이언트가 거부해야 한다 (MUST). 자세한 도구 보안 규칙은 RAWP-DPS 1.0.1 §15를 참조한다.

7.3. Rate Limiting

적용 대상: Rate Limiting은 HTTP 엔드포인트에 대한 요청에 적용된다. WSS 프레임은 Rate Limit 대상이 아니다. WSS는 이미 세션당 단일 연결이므로 별도의 프레임 수준 제한을 두지 않는다.

limits.rate_limit 필드의 의미: §4.1.5에서 클라이언트가 보고하는 limits.rate_limit은 해당 클라이언트가 초당 처리 가능한 최대 HTTP 요청 수를 의미한다. 마스터 서버는 이 값을 초과하는 빈도로 해당 클라이언트에 HTTP 요청을 보내서는 안 된다 (MUST NOT).

429 응답 형식: Rate Limit을 초과한 요청에 대해 429 Too Many Requests를 반환할 때, 다음을 포함해야 한다 (MUST):

{
  "error_code": "RATE_LIMITED",
  "message": "String (휴먼 리더블 디버깅 메시지)",
  "retry_after": "Number (필수, 초 단위, 다음 요청까지 대기해야 할 최소 시간)"
}

Retry-After HTTP 헤더에도 동일한 값을 초 단위로 포함해야 한다 (MUST).

양방향 적용: 마스터가 클라이언트의 rate_limit을 초과하면 클라이언트가 429를 반환하고, 클라이언트가 마스터의 내부 Rate Limit을 초과하면 마스터가 429를 반환한다. 양측 모두 본 절의 응답 형식을 따른다 (MUST).

참조