Skip to content

feat(web): opt-in 웹 가상 터미널 — 컨테이너 내부 셸 (AGT-4002) - #904

Open
unohee wants to merge 1 commit into
mainfrom
heewonoh/agt-4002-web-terminal
Open

unohee wants to merge 1 commit into
mainfrom
heewonoh/agt-4002-web-terminal

Conversation

@unohee

@unohee unohee commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator

무엇

OPENSWARM_WEB_TERMINAL=1일 때만 /terminal 페이지(xterm.js)와 /terminal/ws WebSocket이 생긴다. 셸은 데몬 컨테이너 안의 bash -l이고 uid는 데몬과 같다. cwd는 OPENSWARM_WORKSPACE_ROOT(기본 /work, 없으면 home)이다.

  • 서버 src/support/terminalServer.ts: upgrade 처리, 인증, 세션 상한·idle·정리, 프로토콜 파싱. web.ts에는 시작/정지 호출 두 줄만 넣었다(크기 게이트 때문에 줄 수는 늘리지 않음).
  • 클라이언트 web/static/terminal.html + web/static/js/terminal.js: 풀스크린 xterm, fit addon, 연결 상태 표시, 재연결 버튼.
  • 의존성: ws(runtime), node-pty(optionalDependencies, 세션을 시작할 때만 lazy import), @xterm/xterm·@xterm/addon-fit(dev). postbuild가 scripts/copy-web-vendor.mjs로 dist/web-static/vendor/xterm/에 복사한다(CDN을 쓰지 않음).
  • README·docker-compose에 활성화 방법과 경고(터미널 접근권 = 컨테이너 env 토큰 접근권)를 적었다.

인증 게이트 — 운영자 리뷰 필요

  1. upgrade 이벤트는 web.ts의 요청 핸들러를 거치지 않는다. 그래서 기존 HTTP 게이트가 자동으로 돌지 않는다. authorizeTerminalUpgrade()가 webAuth.ts의 isAuthorizedMutation(토큰, 또는 loopback/신뢰 Tailscale + 신뢰 Origin)을 직접 호출한다. 실패하면 401을 쓰고 socket을 destroy한다.
  2. Origin 추가 검사: 브라우저는 WebSocket에 CORS를 적용하지 않는다. 그래서 Origin 헤더가 있으면 이 데몬 자신의 host:port여야 한다(아니면 거부). 토큰 경로에도 적용한다. 앰비언트 신뢰 경로(loopback/Tailscale)는 게이트 안에서 이미 허용 Origin을 요구하므로, DNS rebinding은 토큰이 없으면 막힌다.
  3. 토큰 운반 방식(신규 carrier): 브라우저 WebSocket은 헤더를 붙일 수 없다. 그래서 웹 토큰을 Sec-WebSocket-Protocol 항목 openswarm.token.<base64url>로 보낸다. 서버는 그 값을 x-openswarm-token에 넣은 뷰로 기존 hasValidWebToken에 다시 묻는다(비교 로직을 새로 만들지 않음). URL에는 절대 넣지 않고, 응답 프로토콜로는 openswarm.terminal.v1만 돌려준다. 이 운반 방식은 새로 만든 것이라 승인이 필요하다.
  4. 동시 세션 4개(초과하면 1013으로 close), 입력 없이 15분이면 종료, 시작·종료·거부를 peer IP와 함께 로그로 남긴다. pty와 socket 중 한쪽이 끝나면 다른 쪽도 정리한다.

검증

  • src/support/terminalServer.test.ts 18건(가짜 pty 주입, 실제 http+ws): 미설정 시 upgrade listener·/terminal 라우트 없음, foreign Origin(loopback이어도, 토큰이 있어도) 거부, 원격 peer는 토큰(헤더/subprotocol) 없거나 틀리면 거부, 다른 경로 upgrade 404, 입출력·resize 중계, 소켓 종료 시 pty kill, 상한 초과 1013, idle 종료, 셸 종료 시 소켓 close
  • src/support 102 files / 1069 tests 통과, tsc --noEmit -p tsconfig.check.json 통과, oxlint 신규 경고 0
  • npm run build → dist/web-static/vendor/xterm/ 3개 파일 생성 확인
  • 실기동(빈 포트 38471, 실제 node-pty, Node 24): /terminal 200, vendor 200, foreign Origin upgrade 401, 정상 세션에서 echo SMOKE-$((6*7)) 출력과 resize 반영(tput cols/lines = 133/41), 종료 로그 확인
  • Docker 빌드(node:22-slim에서 node-pty 컴파일)는 로컬에서 돌리지 않았다(호스트 메모리 규칙). package.json이 바뀌어 Docker Build Check CI가 돈다.
  • 남은 것: 대시보드 헤더의 Terminal 링크(활성 여부 API 필요)는 넣지 않았다.

…GT-4002)

A /terminal page with an xterm.js client and a /terminal/ws WebSocket that
runs `bash -l` inside the daemon's container, for operating a remote daemon
from the browser.

Security model:
- Off unless OPENSWARM_WEB_TERMINAL=1; unset, neither the page route nor the
  upgrade listener is registered.
- The upgrade never enters web.ts's request handler, so terminalServer.ts
  applies the mutation gate from webAuth.ts explicitly (token, or loopback /
  trusted Tailscale with a trusted Origin) and additionally requires any
  browser Origin to be this daemon's own host and port. Refused upgrades get
  401 and the socket is destroyed.
- Browsers cannot set WebSocket headers, so the web token is offered as a
  Sec-WebSocket-Protocol entry (openswarm.token.<base64url>) and re-checked
  through hasValidWebToken; it never appears in the URL, and only the plain
  protocol name is echoed back.
- At most 4 sessions (extra ones closed with 1013), 15-minute idle timeout,
  start/stop logged with the peer address, pty and socket cleaned up on
  either side closing.

Dependencies: ws (runtime), node-pty (optional, imported lazily only when a
session starts), @xterm/xterm + @xterm/addon-fit (dev; postbuild copies them
to dist/web-static/vendor/xterm since the dashboard loads no CDN).
README and docker-compose document the flag and that terminal access equals
access to the container's environment and tokens.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant