feat(gateway): add special account access

docs/admin-console.md

@@ -11,7 +11,7 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로
 | 메뉴          | 경로                      | 책임                                                                           |
 | ------------- | ------------------------- | ------------------------------------------------------------------------------ |
 | 운영 개요     | `/gateway/admin`          | 관리 영역 안내와 빠른 진입                                                     |
-| 사용자 관리   | `/gateway/admin/users`    | 계정 조회·생성, 권한, OAuth 유예, 제재, 아이콘 복구, 탈퇴 예약과 사용자별 이력 |
+| 사용자 관리   | `/gateway/admin/users`    | 계정 조회·생성, 권한, 특수 접근·OAuth 유예, 제재, 아이콘 복구, 탈퇴 예약과 사용자별 이력 |
 | 서버 관리     | `/gateway/admin/servers`  | profile 공개 정보, 계정 정책, 실행 상태와 게임 운영 동작                       |
 | 버전 업데이트 | `/gateway/admin/releases` | profile DB 유지·초기화 배포, Gateway 릴리스·rollback과 작업 이력               |
 | 공지 · 접속   | `/gateway/admin/system`   | 로비 공지와 관리자 세션 연결                                                   |
@@ -34,5 +34,25 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로
 - 브라우저의 메뉴 노출은 편의 기능입니다. 권한 판단의 기준은 서버가 인증
   session에서 해석한 capability입니다.
 
+## Kakao 없는 특수 계정 접근
+
+운영자 role(`superuser`, `admin`, `admin.*`)은 별도 grant 없이 모든 game
+profile에 접근하고 장수를 생성할 수 있습니다. 일반 계정의 예외는 사용자 관리의
+`특수 접근 부여`에서 다음 항목을 명시합니다.
+
+- 종류: 특수 테스트(`TESTER`), 인증 수단 복구(`RECOVERY`), 기타(`OTHER`)
+- profile: 비우면 전체, `che`면 모든 CHE 기수, `che:2`면 해당 기수만
+- 장수 생성: 단순 기존 장수 접속과 신규 장수 생성 권한을 분리
+- 만료: `RECOVERY`는 필수이며 현재 시각부터 최대 90일
+- 사유: 부여·해제 모두 3자 이상이며 감사 원장에 기록
+
+여러 grant가 있으면 현재 profile에 적용되는 유효 grant 중 하나라도 장수 생성을
+허용할 때 생성이 가능합니다. 영구 grant가 하나라도 있으면 접근 만료는 없습니다.
+Kakao 인증이 완료되면 특수 접근이 없어도 정상 접근하며, 계정 제재와 profile별
+server restriction은 특수 접근보다 먼저 적용됩니다. 변경 시 user flush가 발행되어
+다음 game token 발급부터 새 정책이 반영됩니다. 기존 Kakao 연결 계정도 비밀번호를
+확인한 뒤 유효한 grant 기간에는 Kakao 공급자 검증 없이 로그인할 수 있으므로,
+휴대폰 분실 복구에는 반드시 짧은 만료와 확인 사유를 사용합니다.
+
 상세 배포·복구 절차는 [릴리스 운영 매뉴얼](./release-operations.md)을
 따릅니다.

docs/architecture/runtime.md

@@ -26,6 +26,7 @@ TTL, game-token secret, OAuth, local-account 정책과 orchestrator 설정을
 Gateway API는 다음 저장 경계를 사용합니다.
 
 - `AppUser`, `SystemSetting`: 계정과 정책
+- `SpecialAccountAccessGrant`: Kakao 없는 테스트·복구·기타 계정의 profile 범위, 만료, 장수 생성 및 해제 이력
 - `GatewayProfile`: profile, scenario, port, 상태와 build 결과
 - `GatewayOperation`: build/reset/open/close 등 실행 요청과 결과
 - `GatewayReleaseOperation`, `GatewayReleaseState`: Gateway 전체 릴리스 queue와 현재·이전 commit
@@ -67,6 +68,16 @@ Redis script가 원자적으로 성공 소비 또는 실패 횟수 차감(최대
 challenge와 OAuth pending state에는 TTL이 있으며 Redis 장애나 메시지 발송 실패는
 로그인 실패로 끝납니다.
 
+Kakao 없는 게임 접근은 Gateway에서만 판정합니다. 비밀번호와 제재를 먼저 검사한 뒤
+운영자 또는 유효한 특수 grant가 있는 기존 Kakao 연결 계정은 공급자 호출 없이
+Gateway session을 발급합니다. 게임 profile 진입에서는 다시 제재 검사를 수행하고
+Kakao 확인, 운영자 role, 유효한 `SpecialAccountAccessGrant`, 기존 일반 계정 유예
+순으로 접근과 장수 생성 가능 여부를 계산합니다. grant의 빈 `profiles`는 전체,
+base profile(`che`)은 모든 기수, profile name(`che:2`)은 정확한 기수를 뜻합니다.
+결과는 AES-256-GCM game token의 `identity.specialAccess`와
+`identity.canCreateGeneral`에 서명되어 game API가 장수 생성 mutation 전에 다시
+검사합니다. grant 사유나 부여자 정보는 game token에 넣지 않습니다.
+
 Orchestrator는 `GatewayOperation`을 claim하고 source ref를 commit으로
 해결합니다. `WorkspaceManager`가 commit별 worktree를 준비하고 build runner가
 artifact를 만들며 `Pm2ProcessManager`가 profile process를 조정합니다.