Files
joke-app/docs/04-stability-security.md
EJClaw 84d64b27f2 컴퓨터 난이도 1~60단계·방장 선택·판마다 변화·운, 공정성 확인에 표기, 업데이트 알림 팝업
- 난이도 1~60(쉬움 1~20·보통 21~40·어려움 41~60): 넣을 때 랜덤, 방장이 대기실에서 [랜덤][쉬움][보통][어려움] 선택(botLevel) → 범위 안 무작위
- 다음 판마다 -2~+2, 처음 단계 ±5·같은 범위 안(drift); 말투는 처음 단계(>30 존댓말)
- humanBest 확률을 단계별로 보간(BOT_PLAY_ANCHORS: 1·10·30·50·60)
- 운(-1~+1): 카드·주사위 게임에서 시작 전에 시드 후보 1~5개를 작업 스레드에서 끝까지 둬 보고 운에 맞는 것을 고름(luck.ts, luck-worker.ts). 해시 공개는 그대로
- 결과 화면 공정성 확인에 컴퓨터별 단계·운, 섞어 본 후보 수
- 업데이트 알림: 빌드 ID meta + /api/version + welcome.build → 상단 팝업 [지금 새로고침하기] [✕]
- 문서 03·04 §5.1·06 §12·07 §11.1·09 §9.1, 테스트(bot-level.room, luck, version, e2e bots·pwa)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 17:46:13 +09:00

91 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 04. 안정성과 보안
## 1. 목표
- 어떤 상황에서도 진행 중인 게임 상태를 잃지 않는다(프로세스 충돌, 배포, 서버 재부팅).
- 한 방의 버그가 다른 방이나 서버 전체를 멈추지 않는다.
- 클라이언트를 조작해도 규칙을 어기거나 남의 패를 볼 수 없다.
## 2. 상태 저장 방식
- 방 상태는 메모리에 있고, **행동이 하나 처리될 때마다** 같은 동기 트랜잭션으로 SQLite에 기록한다.
- `room_log`에 행동 한 줄 추가(누가, 무엇을, 서버 시각, seq) — 기록 보기·리플레이·디버깅용.
- `room_state`에 최신 전체 상태(게임 상태 + RNG 상태 + 타이머 마감 + 자리 정보) 덮어쓰기.
- 상태는 작으므로(대부분 수 KB) 매번 전체 저장이 가장 단순하고 확실하다. SQLite WAL + `synchronous=NORMAL`로 한 번 쓰기 1ms 미만 목표(테스트로 확인).
- 저장이 끝난 다음에만 다른 사람에게 결과를 보낸다(보낸 상태 = 저장된 상태).
- `synchronous=NORMAL`은 프로세스가 죽어도 데이터가 남는다. 정전 같은 OS 단위 장애에서는 마지막 몇 개 행동을 잃을 수 있고, 이는 허용한다.
## 3. 서버 시작 시 복구
1. `rooms`에서 `status IN ('lobby','playing')`인 방을 읽는다.
2. 각 방의 `room_state`를 불러 메모리 Room을 만든다. 모든 플레이어는 "연결 끊김" 상태로 시작.
3. 저장된 `deadline`이 이미 지났다면 복구 직후 일괄 처리하지 않고, **복구 시각 + 30초 + 0~30초 무작위**로 마감을 미뤄 준다(재접속할 시간, 많은 방이 한순간에 시간 초과되는 몰림 방지).
4. 복구 실패(스키마 불일치, 게임 코드 변경으로 상태가 안 맞음)한 방은 `status='broken'`으로 표시하고, 들어온 사람에게 "서버 업데이트로 이 게임을 이어갈 수 없어요. 새로 시작해 주세요"를 보여 준다.
5. 게임 규칙 코드가 바뀌어 저장 상태 형식이 달라지면, 그 게임 모듈의 `stateVersion`을 올리고 `migrate(oldState)`를 제공하거나 위 4번으로 처리한다.
## 4. 장애 격리
- 게임 모듈의 `apply/view` 호출은 try/catch로 감싼다. 예외가 나면:
- 그 행동은 적용하지 않음(상태는 직전 그대로), 행동한 사람에게 `reject`("알 수 없는 오류가 발생했어요").
- 오류 로그에 방 코드, 게임, seq, 행동, 스택을 남긴다.
- 같은 방에서 오류가 3번 연속 나면 방을 "일시 정지"하고 방장에게 "게임 끝내기(무효)"를 제공.
- `view()`에서 예외가 나면 그 사람에게만 오류 화면, 다른 사람에게는 정상 전송.
- 프로세스 수준 `uncaughtException`/`unhandledRejection`은 로그 후 종료 → Docker `restart: unless-stopped`가 재시작 → 3절로 복구.
- 무한 루프 방지: 게임 규칙 함수에 단위 테스트 + 무작위 대국 테스트로 처리 시간 상한(5ms) 확인.
## 5. 숨겨진 정보와 공정성
- 클라이언트에는 `view(state, viewer)` 결과만 보낸다. 덱 순서, 남의 패, 마피아 직업, RNG 시드는 절대 보내지 않는다.
- 게임마다 "정보 유출 테스트": 무작위 대국을 돌리며 매 순간 플레이어 A의 view(JSON 문자열)에 다른 사람만 알아야 하는 값(카드 ID 등)이 들어 있지 않은지 검사.
- 셔플: 게임 시작 시 `crypto.getRandomValues`로 256비트 시드를 만들고, 상태 안의 암호학적 난수 생성기 ChaCha20(RFC 8439)으로 Fisher–Yates 셔플·주사위·뽑기(2026-10-11). 지금까지 나온 카드·주사위를 아무리 봐도 다음 값을 알 수 없다. 그 전에 시작된 게임은 sfc32(128비트) 그대로라 다시 보기가 같다.
- **공정성 확인(선택 표시)**: 게임 시작 때 시드의 SHA-256 해시를 모두에게 공개하고, 게임이 끝나면 시드를 공개한다. 결과 화면의 "공정성 확인"을 누르면 같은 시드로 덱을 다시 만들어 실제 배분과 같은지 브라우저가 확인한다.
- **컴퓨터의 운(2026-10-11, §5.1)**: 컴퓨터가 있는 연습 게임에서는 시작 전에 시드를 몇 개 만들어 보고 그중 하나를 고른다. 고른 시드의 해시를 시작할 때 공개하는 것은 같으므로, 게임 중에 카드 순서나 난수가 바뀌지 않는다는 보장은 그대로다.
- 관전자에게는 공개 정보만. 포커·섯다처럼 관전이 정보 누설 통로가 될 수 있는 게임은 기본적으로 "관전 지연 표시 없음 + 공개 정보만"이고, 같은 사람이 플레이어와 관전자를 동시에 할 수 없다.
### 5.1 컴퓨터의 운 (2026-10-11)
사람처럼 컴퓨터마다 운이 다르다. 운이 좋으면 패가 잘 들어오고, 난이도가 높아도 운이 나쁘면 패가 잘 안 들어와 어려워진다.
- 운: 컴퓨터를 넣을 때 OS 보안 난수로 -1(아주 나쁨)~+1(아주 좋음)에서 하나 정해지고 그 방에 있는 동안 그대로다(난이도를 바꿔도 유지). 결과 화면 "공정성 확인"에 아주 나쁨(≤-0.6)·나쁨(≤-0.2)·보통·좋음(≥0.2)·아주 좋음(≥0.6)으로 보인다.
- 섞기 후보 수: `1 + round(|운| × 4)`. 운이 0 근처(|운|<0.125)면 1개(고르지 않음), ±1이면 5개(`MAX_SHUFFLES`). 컴퓨터가 여럿이면 가장 센 운 기준.
- 고르는 법(`chooseLuckySeed`, `packages/games/src/bots/luck.ts`): 후보마다 새 OS 시드로 게임을 한 번 끝까지 둬 본다(모든 자리를 컴퓨터가 둠, 사람 자리는 30단계). 각자의 등수를 0(꼴찌)~1(1등) 점수로 바꾸고, Σ(컴퓨터의 운 × 그 컴퓨터 점수)가 가장 큰 시드를 쓴다. 운이 좋은 컴퓨터는 잘 풀렸던 배분을, 나쁜 컴퓨터는 안 풀렸던 배분을 받는 셈이다. 실제 게임은 사람이 다르게 두므로 결과는 여전히 정해지지 않는다.
- 대상: 카드·패·타일·주사위·숨은 역할이 있는 컴퓨터 게임. 오목·오셀로·체스·장기·바둑·쿼리도(섞는 게 선후뿐), 마피아(말하는 컴퓨터, 시뮬레이션 없음)는 운을 쓰지 않는다.
- 서버 부담: 시뮬레이션은 방 스레드가 아닌 작업 스레드(`apps/server/src/rooms/luck-worker.ts`) 하나에서 순서대로 한다. 첫 후보 뒤로는 1.5초(`LUCK_BUDGET_MS`)를 넘기면 더 만들지 않고, 8초 안에 답이 없거나 실패하면 새 시드 하나로 시작한다. 그동안 대기실은 "🃏 섞는 중…"이고 설정·자리·난이도를 바꿀 수 없다. 그사이 자리가 바뀌면 시작하지 않는다.
- 공개: 결과 화면 "공정성 확인"에 컴퓨터별 난이도·운과 "미리 섞어 본 N가지 중 하나로 시작했어요"를 보인다. 연습 게임은 전적에 들어가지 않는다(06 §12).
- 효과(컴퓨터 1:1, 고른 배분으로 수는 새로 골라 끝까지 둠, 컴퓨터의 평균 점수, 0.5 = 반반, 운별 80판):
| 게임 | 운 +1 | 운 0 | 운 -1 |
|---|---|---|---|
| 원카드 | 0.63 | 0.60 | 0.41 |
| 섯다 | 0.54 | 0.44 | 0.36 |
| 포커 | 0.72 | 0.41 | 0.25 |
| 요트 | 0.79 | 0.48 | 0.17 |
사람은 컴퓨터와 다르게 두므로 실제 효과는 이보다 조금 약할 수 있다(특히 주사위 게임은 두는 수에 따라 뒤 주사위가 달라진다).
- 테스트: `packages/games/src/bots/luck.test.ts`(후보 수, 대상 게임, 운 좋은 쪽이 더 잘함), `apps/server/src/rooms/luck.test.ts`(실제 작업 스레드, 실패·시간 초과 대비), `apps/server/src/rooms/bot-level.room.test.ts`(섞는 동안 대기, 고른 시드로 시작, 자리 바뀌면 취소).
## 6. 사행성·법적 주의
- 포커·섯다·고스톱 등은 **방 안에서만 쓰는 가상 칩/점수**를 쓴다. 방이 끝나면 사라지고, 계정에 쌓이지 않으며, 사고팔거나 바꿀 수 없다. 결제·유료 아이템·충전도 없다.
- 기록에는 "몇 판 이겼는지"만 남기고 칩 잔액은 남기지 않는다.
- 이 구조는 게임산업진흥법의 사행성 관련 위험을 피하기 위한 것이다(법률 자문 아님). 수익화를 하게 되면 그 전에 반드시 법률 검토를 받는다.
- 상표: 루미큐브, 우노, 뱅!, 스플렌더, 할리갈리, 다빈치 코드, 모두의 마블 등은 상표다. 공개 서비스로 열기 전에 화면 표시 이름을 일반 명칭으로 바꿀지 사용자 결정을 받는다(`games/README.md` 4절). 카드·화투 그림은 직접 만든 SVG만 쓴다.
## 7. 웹 보안
| 위협 | 대응 |
|---|---|
| 세션 탈취 | 세션 토큰은 32바이트 무작위, DB에는 SHA-256 해시만 저장. 쿠키 `HttpOnly; Secure; SameSite=Lax; Path=/` |
| CSRF | 상태를 바꾸는 HTTP API는 POST + `Origin` 검사 + `SameSite=Lax` |
| CSWSH | WS 업그레이드 때 `Origin` 검사 |
| XSS | React 기본 이스케이프, `dangerouslySetInnerHTML` 금지(린트), 닉네임·채팅은 일반 텍스트. CSP: `default-src 'self'; img-src 'self' https://cdn.discordapp.com data:; connect-src 'self' wss://<도메인>; frame-ancestors 'none'` |
| 메시지 폭주 | 3장 8절의 속도·크기 제한, 사용자당 동시 연결 5개, IP당 분당 방 생성 10개 |
| 방 코드 무작위 대입 | 코드 입력 API는 IP당 분당 30회 제한, 6자리(100만 개) 중 사용 중인 코드는 수백 개 수준 |
| 잘못된 입력 | 모든 메시지 zod 검사, 게임 `validate()`가 한 번 더 검사 |
| 비밀값 | 디스코드 client secret, 세션 서명 키는 `.env`(저장소에 올리지 않음) |
## 8. 채팅 안전(어린이 사용자 고려)
- 방 옵션: 채팅 켜기/끄기(기본 켜짐), 욕설 필터(기본 켜짐, 단어 목록 기반 `***` 치환).
- 각 사용자는 특정 사람의 채팅을 "숨기기" 가능(내 화면에서만).
- 빠른 반응(이모트)은 고정 목록이라 항상 안전.
- 닉네임에도 같은 욕설 필터 적용.
## 9. 운영 안정성
- 로그: JSON 한 줄 로그(시간, 레벨, 방, 사용자, 이벤트). 게임 행동 내용은 `room_log`에만.
- 지표: `/internal/metrics`(외부 차단) — 연결 수, 방 수, 행동 처리 시간 히스토그램, 저장 시간, 오류 수, 메모리.
- 백업: 매일 SQLite `VACUUM INTO`로 백업 파일 생성, 14일 보관. 복구 절차는 `11-deployment-ops.md`.
- 정리: 아무도 없는 대기실 10분 후 삭제, 끝난 방 30분 후 메모리에서 내림(기록은 DB에 남음), 게임 중·끝난 방은 플레이어가 모두 사이트를 닫으면 1분 후 닫음(06 §11), 오래된 `room_log`는 90일 후 삭제.
- 무중단에 가까운 배포: 새 버전 시작 전 옛 버전이 `bye: restart`로 안내 → 재시작(수 초) → 자동 재연결·복구.