security: 운영 API 무토큰 LAN 노출은 의도된 결정(Tailscale·LAN 신뢰 경계) — 문서에 기록 + /ws·/tui·/hooks 문서 등재

[itismyfield]

결정 (사용자, 2026-09-05)

운영 API 노출 경계는 현행 유지한다. server.host: 0.0.0.0, server.auth_token 미설정, allow_insecure_nonloopback_bind: true. 근거: 운영 기기가 Tailscale로 묶여 있고, 같은 로컬 네트워크(집)의 기기도 신뢰한다. (대안 "Tailscale 주소에만 바인드"와 "auth_token 설정"은 기각. 2026년 7월 결정을 재확인한 것.)

이 결정은 코드가 #3870에서 넣은 fail-closed 안전장치를 플래그로 의도적으로 해제한 것이므로, 결정이 문서에 남아 있지 않으면 다음 사람이 사고로 오인한다. 본 이슈는 결정을 문서에 박고, 그 결정과 무관하게 남는 작은 정합 항목을 정리한다.

할 것

1. 결정 기록. docs/source-of-truth.md(또는 docs/security-boundary.md 신설)에 "운영 API는 LAN·Tailscale 신뢰 경계 안에서 토큰 없이 노출한다. allow_insecure_nonloopback_bind: true는 의도된 설정이다. 이 경계를 벗어나는 배포(외부 노출, 공용 네트워크)에서는 auth_token 필수"를 명시. 부팅 시 security: 컨트롤플레인 기본 fail-open — non-loopback bind를 토큰 없이도 허용(경고만) #3870 안전장치가 해제됐을 때 찍는 로그 문구에 이 문서 경로를 넣는다.
2. API 문서 등재. /ws, /tui/*, /hooks/*가 /api/docs 인벤토리(routes/docs/inventory)에 없다. 등재하고, /ws는 ?token= 쿼리 인증, /tui/*·/hooks/*는 "loopback 또는 Bearer" 규칙(routes/auth.rs:34-38)임을 적는다.
3. /ws 토큰 전달 방식. 현재 URL 쿼리(ws.rs:33-36). 토큰을 쓰는 배포에서는 URL이 로그·프록시에 남으므로 Sec-WebSocket-Protocol 또는 첫 프레임으로 옮긴다. 본 결정(토큰 미사용)에서는 영향 없으므로 P3, 별도 PR 가능.
4. 요청 제한(rate limit). /api/*에 없음. 신뢰 경계 안 노출이므로 본 이슈에서는 하지 않고 기록만 남긴다.

완료 정의

• 문서에 결정·근거·재검토 조건 기재, security: 컨트롤플레인 기본 fail-open — non-loopback bind를 토큰 없이도 허용(경고만) #3870 해제 로그가 그 문서를 가리킴
• /api/docs에 /ws, /tui/*, /hooks/* 등재 + 인증 규칙 기재
• /ws 토큰 헤더 이전 (P3, 선택)
• agentdesk doctor가 "auth_token 미설정 + 비loopback 바인드" 상태를 경고가 아니라 정보로 표시하고 문서 링크를 붙임 (결정된 상태를 매번 경고로 띄우지 않음)

관련

• security: 컨트롤플레인 기본 fail-open — non-loopback bind를 토큰 없이도 허용(경고만) #3870 (비loopback 바인드 + 토큰 없음 fail-closed 도입)
• cluster: 채널 소유 기반 게이트웨이 인그레스로 leader forwarding 계층 대체 (첨부 멀티노드 미지원·채널 failover 포함) #5713 (채널 소유 게이트웨이 설계. 노드 간 API 호출이 이 경계 안에서 이루어짐)
• 기준: main 01c0c078d8, 운영 agentdesk.yaml server 절