API_SPEC.md

API Spec Draft

Auth

운영 서버로 실행하는 Control Plane과 Quarantine Gateway는 기본적으로 다음 헤더를 요구합니다.

Authorization: Bearer <govmesh-token>

역할은 agent, operator, auditor, importer, approver로 나뉩니다. /health는 로컬 상태 점검을 위해 공개로 둘 수 있지만, 노드/작업/감사/반입 상태 변경 API는 역할 검사를 통과해야 합니다.

mTLS를 프록시에서 종단하는 환경에서는 다음 헤더를 allowlist 검증에 사용할 수 있습니다.

X-Client-Cert-SHA256: <client-certificate-sha256>

기관 SSO를 프록시에서 종단하는 환경에서는 다음 서명 헤더를 사용할 수 있습니다.

X-GovMesh-User: <sso-user-id>
X-GovMesh-Roles: operator,auditor
X-GovMesh-Issued-At: <unix-seconds>
X-GovMesh-Proxy-Signature: <hmac-sha256>

서명되지 않은 SSO 사용자/역할 헤더는 신뢰하지 않습니다.

Control Plane

Method	Path	Purpose
POST	/nodes/register	노드 등록
POST	/nodes/{node_id}/heartbeat	노드 상태 보고
GET	/nodes	노드 목록
POST	/tasks	작업 생성
GET	/tasks/next	다음 작업 조회
POST	/tasks/{task_id}/result	작업 결과 보고
POST	/audit/events	감사 이벤트 기록
GET	/benchmarks	벤치마크 결과 목록

Quarantine Gateway

Method	Path	Purpose
POST	/imports/upload	반입 파일 업로드
GET	/imports/{id}	반입 상태 조회
POST	/imports/{id}/scan	해시와 위험 패턴 검사
POST	/imports/{id}/sanitize	텍스트 계열 반입물 CDR/마스킹 산출물 생성
POST	/imports/{id}/approve	승인
POST	/imports/{id}/reject	반려
GET	/imports/approved	승인된 반입물 목록

Skill Registry

Method	Path	Purpose
POST	/skills/drafts	skill 초안 등록
POST	/skills/{id}/review	검토 요청
POST	/skills/{id}/approve	승인
POST	/skills/{id}/reject	거부
POST	/skills/{id}/deploy	배포

Review Queue

Method	Path	Purpose
POST	/reviews	사람 검토 항목 생성
GET	/reviews	검토 항목 목록
POST	/reviews/{id}/decision	승인/반려/추가정보 요청

Response Rules

• 정책 차단 응답은 block_reason, risk_level, user_message를 포함해야 합니다.
• 감사 가능한 변경 응답은 audit_event_id를 포함해야 합니다.
• PII 원문은 응답 또는 로그에 남기지 않습니다.