docs: 13단계 전환 준비 — 계약 6절 · 디자인 보드 넷 · README

관리자가 준 임시 비밀번호 바꾸기 · 2단계 인증 필수 · 메일 프로그램 연결 안내 · 받은편지함 알림 메일 · 휴지통 30일 안내와 서버 안 운영 도구를 정했다.
엔진 실험(Stalwart 0.16.27): 계정 끄기 칸이 없어 로그인 권한을 빼서 잠그고, 비밀번호가 만료되면 웹메일(대리 접근)도 메일 메서드가 막혀 서버가 새 비밀번호 단계로 보낸다.
사용자 결정(2026-10-31): 새 비밀번호 단계는 다음 코드를 기다려 넣고, 필수 직원의 휴대폰 바꾸기는 관리자 해제, 알림 메일에는 링크를 넣지 않고, 새 Outlook 은 권하지 않는다.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/mail/api-contract.md

@@ -9,7 +9,7 @@
 - 성공 `{ "success": true, "data": … }` / 실패 `{ "success": false, "error": { "code", "message", "traceId" } }`
 - 날짜·시각은 ISO 8601 UTC 문자열, 목록은 `{ items, pageInfo }`
 - 이 단계에서 쓰는 에러 코드: `AUTH_001` `AUTH_002`(클라이언트 전용) `AUTH_003` `AUTH_004` `AUTH_005` `VAL_001` `RES_001` `REQ_001` `FILE_001` `FILE_002` `MAIL_001` `MAIL_002` `MAIL_003` `MAIL_004` `MAIL_005` `MAIL_006` `MAIL_007` `MAIL_008` `MAIL_009` `MAIL_010` `MAIL_011` `MAIL_012` `MAIL_013` `MAIL_014` `MAIL_015` `CONTACT_001` `CONTACT_002` `SYS_001`
-  (11단계 — 4절 "대용량 첨부"가 `FILE_003` ~ `FILE_008` · `MAIL_016` 을 더한다. 12단계 — 5절 "계정 보안"이 `AUTH_006` ~ `AUTH_009` 를 더한다)
+  (11단계 — 4절 "대용량 첨부"가 `FILE_003` ~ `FILE_008` · `MAIL_016` 을 더한다. 12단계 — 5절 "계정 보안"이 `AUTH_006` ~ `AUTH_009` 를, 13단계 — 6절 "전환 준비"가 `AUTH_010` 을 더한다)
 - **적용 범위: 1단계는 웹(브라우저) 전용이다.** 인증은 HttpOnly 쿠키뿐이고 토큰을 본문으로 주지 않는다.
   모바일 앱(Flutter)의 인증 방식(토큰 발급·`flutter_secure_storage`)은 앱 착수 때 이 문서에 추가한다.
 - **배포 형태: 화면과 API 는 같은 주소(origin)를 쓴다.** 운영은 프론트 nginx 가 `/api` 를 백엔드로 넘기고,
@@ -2040,7 +2040,7 @@ interface FileUploadCreate {
 기간 고르기 · 연장, 다시 보내기(다시 올리지 않고 새 링크), 받는 사람 확인 코드 · 비밀번호, 사내만(로그인해야 받기), 받는 사람별 링크 · 기록, 처음 받음 · 만료 전 알림, 미리 보기, 모두 받기(zip), 폴더 올리기,
 파일 하나만 끊기(끊기는 링크 단위), 설정 목록의 [링크 복사](토큰을 되살릴 수 없다 — 보낸 메일의 덩이에서), 대용량 첨부만 있는 메일의 목록 클립, 링크 → 일반 첨부로 되돌리기,
 전달 원본 · 임시 저장본의 엔진 첨부를 링크로 바꾸기, 인용 속 원래 링크를 다시 싣기,
-관리자 화면 · 퇴사자 처리(신고를 받은 링크는 그때까지 운영 스크립트로 끊는다 — 구현하며 정함), 보낸 메일을 지울 때 파일도 지우기, 모바일 앱, 파일 저장소 연동,
+관리자 화면 · 퇴사자 처리(신고를 받은 링크 끊기 · 퇴사자 잠금은 13단계의 운영 도구 — 6절), 보낸 메일을 지울 때 파일도 지우기, 모바일 앱, 파일 저장소 연동,
 다른 PC · 다른 브라우저에서 이어 올리기(같은 브라우저에서 같은 파일을 다시 고르면 이어진다).
 
 ### 정한 것 (열린 질문이었던 것 — 2026-10-30 추천대로)
@@ -2121,7 +2121,7 @@ interface FileUploadCreate {
      있으면: 다시 쓴 코드인지 보고 → 코드 실패 한 번을 차지하고 → 엔진 `POST /api/auth`(`accountSecret` + `mfaToken`)에 묻는다.
      `authenticated` 면 로그인한다(차지한 것을 돌려주고 코드를 2분 기억). `failure` 면 `AUTH_006`.
   5. 401 → `AUTH_004`.
-- **지금은 402 를 엔진 장애(503 `MAIL_001`)로 다룬다 — 고친다.** 운영자가 엔진 관리 화면에서 OTP 를 켠 직원은 지금 웹메일에 들어오지 못한다. 4단계 비밀번호 바꾸기도 같다.
+- **12단계 전에는 402 를 엔진 장애(503 `MAIL_001`)로 다뤘다 — 12단계에서 고쳤다.** 그때는 운영자가 엔진 관리 화면에서 OTP 를 켠 직원이 웹메일에 들어오지 못했고, 4단계 비밀번호 바꾸기도 같았다.
 - 코드 단계에서도 비밀번호를 엔진 Basic 으로 먼저 보는 까닭: `/api/auth` 의 `failure` 는 비밀번호 틀림과 코드 틀림을 가르지 않는다. 비밀번호를 추측하는 요청이 코드 실패로 세지지 않게 한다.
 - `twoFactorRequired` 는 비밀번호가 맞았다는 뜻이다(2단계 로그인의 성질 — 코드 없이는 들어오지 못한다). 비밀번호 추측은 1절의 실패 한도가 그대로 막는다.
 - 엔진 `/api/auth` 가 성공하면 엔진 메모리에 1회용 OAuth 코드가 남는다(쓰지 않으면 10분 뒤 사라진다) — 쓰지 않는다.
@@ -2375,3 +2375,160 @@ interface FileUploadCreate {
 3. 2단계를 켜거나 꺼도 다른 세션을 끊지 않는다 — 로그인 기록 화면에서 따로 끊는다.
 4. 비밀번호를 바꾸면 앱 비밀번호도 모두 지운다(위 "비밀번호 바꾸기").
 5. 다른 곳 로그아웃은 바로 적용한다 — 끊은 세션 id 를 가드가 막는다(위 "로그인된 브라우저"). 로그아웃 · 비밀번호 바꾸기의 세션 끊기도 같다.
+
+---
+
+## 6. 전환 준비 — 13단계 (2026-10-31 확정)
+
+> 운영 도구 · 계정 잠금 · 비밀번호 바꾸기 강제 · 2단계 인증 필수 · 받은편지함 알림 · 문의 연락처.
+> 백업 · 감시 · 휴지통 비우기 시각 · 메일 프로그램 자동 설정 · 관리자 계정 단단히는 인프라 몫이다(mail/README).
+> 근거: 개발 엔진 실험(2026-10-31) — 계정 막기 변형 표, 비밀번호 만료 동작, 관리자 대리 로그인, 엔진 변경과 웹메일 세션.
+
+### 공유 계약을 바꾸는 곳 (한데 모음)
+
+- `POST /api/auth/login`(`signedIn`) · `GET /api/auth/me` · `POST /api/auth/refresh` 응답에 `restriction`(`null` · `passwordChange` · `twoFactorSetup`)과
+  `twoFactorDeadline`(2단계 필수의 유예 중이면 시작일 0시(KST)의 시각 — ISO 8601 UTC, 아니면 `null`)을 더한다.
+- 제한된 세션으로 다른 API 를 부르면 403 `AUTH_010` 이다.
+- `GET /api/two-factor` 응답에 `isRequired`(이 직원에게 필수인가) · `deadline`.
+- 새 공개 API `GET /api/support-contact`(로그인 없음).
+- 운영 도구(서버 안 명령)는 API 가 아니다 — 아래 "운영 도구".
+- 에러 코드 `AUTH_010`.
+
+### 엔진 사실 (이 절이 기대는 것 — 0.16.27)
+
+- 엔진 계정에는 "끄기" 칸이 없다. 로그인 권한(`authenticate`)을 빼면 비밀번호 · 앱 비밀번호 · 대리 접근(웹메일)이 모두 막히고 메일은 계속 받는다. 되돌리기 쉽다.
+- 비밀번호 자격의 만료(`expiresAt` 을 지난 날로)는 그 계정의 권한을 비밀번호 바꾸기만으로 줄인다: 본인 Basic 은 200 이지만 권한이 다섯
+  (`authenticate` · `authenticateWithAlias` · `sysAccountPasswordGet` · `sysAccountPasswordUpdate` · `emailReceive`)뿐이고, 본인이 바꾸면 엔진이 만료를 스스로 푼다. 앱 비밀번호는 영향이 없다(자체 만료).
+  - 웹메일(대리 접근)도 세션은 열리지만 메일 메서드가 `forbidden` 이다 — 그대로면 로그인 뒤 메일 오류만 보인다. 그래서 서버가 로그인 때 알아채 새 비밀번호 단계로 보낸다(아래 "비밀번호 바꾸기 강제").
+  - 만료된 동안은 대리 접근으로 메일을 넣거나 앱 비밀번호를 지우는 일도 막힐 것이다(구현 때 확인) — 그래서 운영 도구는 그 일을 만료를 걸기 전에 한다(아래 "운영 도구").
+- 엔진에서 비밀번호를 바꾸거나 막아도 웹메일 세션은 끊기지 않는다. 갱신이 게이트웨이로 계정이 있는지만 보고, 엔진에는 바뀐 것을 알리는 칸이 없다.
+  - 그래서 운영 도구가 세션을 직접 끊는다.
+- 엔진에는 2단계 인증을 강제하는 설정이 없다 — 서버 정책으로 둔다.
+- 대리 접근으로 직원 받은편지함에 메일을 넣을 수 있다(`Email/import`). 안 읽음 · 실시간 알림이 가고, 필터 · 스팸 판정은 거치지 않는다.
+
+### 제한된 세션
+
+- 로그인은 성공해 쿠키를 받지만 세션에 제한이 붙는다. 제한은 서버(세션 표)에 있고, 액세스 토큰에도 싣는다.
+- 제한된 세션으로 부를 수 있는 것
+  - `/api/auth/*`(me · refresh · logout · password · sessions)
+  - `/api/two-factor` · `/api/two-factor/enrollments` · `/api/two-factor/activation`
+  - `/api/support-contact`
+  - 그 밖은 403 `AUTH_010` 이다.
+- 차례: `passwordChange` 가 먼저, 그다음 `twoFactorSetup`.
+- 푸는 요청(비밀번호 바꾸기 · 2단계 켜기)이 성공하면 서버가 세션의 제한을 지운다. 클라이언트는 곧바로 `/auth/refresh` 로 새 토큰을 받는다.
+  - 다음 제한이 남아 있으면 그 제한이 붙어 온다.
+- 새로고침 · 다른 탭에서도 같은 제한이다(서버가 막는다). 화면은 `me` 의 `restriction` 을 보고 로그인 틀의 그 단계로 간다.
+- 클라이언트는 403 `AUTH_010` 을 받으면 알림 없이 `me` 를 다시 받아 그 제한의 단계로 간다. 제한된 동안은 실시간 알림(`/api/mail-events`)도 열지 않는다 — 제한이 풀린 뒤 연다.
+
+```jsonc
+// POST /api/auth/login → 200 + Set-Cookie — 제한된 세션도 쿠키를 받는다
+{ "status": "signedIn", "email": "ara.kim@arasystem.it.kr", "name": "김아라", "restriction": "passwordChange", "twoFactorDeadline": null }
+// GET /api/auth/me → 200 — 2단계 필수의 유예 중(시작일 2026-12-01)
+{ "email": "ara.kim@arasystem.it.kr", "name": "김아라", "restriction": null, "twoFactorDeadline": "2026-11-30T15:00:00.000Z" }
+```
+
+### 비밀번호 바꾸기 강제 (`restriction: passwordChange`)
+
+- 언제: 엔진의 비밀번호가 만료됐을 때다. 운영 도구의 입사 · 비밀번호 재설정이 건다.
+- 알아채는 법: 로그인 때 본인 자격으로 엔진에 묻는다(권한이 비밀번호 바꾸기뿐인가 — 방법은 구현 때 정한다).
+  - 알아챈 제한은 세션에 남는다 — 갱신은 게이트웨이라 다시 알아채지 못하므로.
+- 푸는 법: `PUT /api/auth/password` — 지금 비밀번호는 임시 비밀번호, 새 비밀번호, 2단계를 켰으면 `otpCode`.
+  - 성공하면 엔진의 만료가 풀리고 세션 제한을 지운다.
+  - 다른 세션 끊기 · 앱 비밀번호 지우기는 5절 규칙 그대로다.
+- **클라이언트**: 로그인 직후면 방금 넣은 비밀번호를 화면 메모리(반응형이 아닌 클로저 — 5절 코드 단계와 같다)에서 지금 비밀번호로 쓴다.
+  10분이 지났거나 새로고침 · 다른 탭이면 「임시 비밀번호」 칸을 보인다.
+- 2단계를 켠 직원은 비밀번호 → 코드 → 이 단계이고, 이 단계에서 코드를 한 번 더 받는다(`otpCode` — 엔진이 비밀번호를 바꿀 때 코드를 요구한다).
+  로그인 때 쓴 코드는 2분 동안 다시 받지 않으므로(5절) 앱의 다음 코드를 넣는다. 서버가 로그인 코드를 기억해 다시 쓰지 않는다 — 새 비밀번호를 치는 사이 코드의 유효 시간(앞뒤 30초)을 지날 수 있다.
+- 엔진이 만료와 2단계 중 무엇을 먼저 보는지는 구현 때 확인한다.
+
+### 2단계 인증 필수 (`restriction: twoFactorSetup`)
+
+- 정책은 서버 설정이고 운영 도구로 바꾼다: 꺼짐 / 켜짐 + 시작일 + 예외 주소. 처음 값은 꺼짐이다.
+- 시작일 전(유예): 로그인은 그대로다. `twoFactorDeadline` 에 시작일이 오고, 화면이 메일함 위에 안내 줄을 보인다(날짜는 그 1ms 앞 — 시작일 전날, 부재중의 끝나는 날과 같은 규칙).
+- 시작일부터: 2단계를 켜지 않은 직원(예외 주소 빼고)의 로그인에 `restriction: twoFactorSetup` 이 붙는다. 화면은 로그인 틀의 켜기 단계로 간다.
+  - 로그인은 엔진의 답(402 면 켜짐)으로, 갱신은 정책과 우리 기록(`two_factor_settings`)으로 다시 본다 — 시작일이 지나면 이미 로그인한 세션도 다음 갱신(최대 1시간) 때 제한이 붙는다.
+  - 켜기는 12단계 API(`enrollments` · `activation`) 그대로다. 지금 비밀번호는 위 "클라이언트"와 같은 규칙이다.
+  - 켜면 세션 제한을 지운다. 화면은 받은편지함으로 가며 [앱 비밀번호 만들기] 알림을 띄운다(디자인 README 13단계).
+- `GET /api/two-factor` 의 `isRequired` · `deadline` 으로 설정 화면도 같은 안내를 보인다. 필수인 직원은 끄기 단추가 없다 — 서버도 400 `VAL_001` 로 거절한다.
+- 필수인 직원이 휴대폰을 바꿀 때는 관리자가 운영 도구의 「2단계 해제」를 하고, 다음 로그인 때 새 휴대폰으로 켠다(직원이 켜진 채 새 휴대폰을 등록하는 길은 이 단계에 없다).
+- 메일 프로그램은 앱 비밀번호로 연결한다(12단계 그대로).
+
+### 문의 연락처 (`GET /api/support-contact`)
+
+```jsonc
+// GET /api/support-contact → 200 (로그인 없음)
+{ "text": "IT 담당 홍길동 · 02-000-0000 · 사내 메신저 @it" }   // 정하지 않았으면 null
+```
+
+- 운영 도구로 바꾼다(서버 설정). 200자 이하 · 한 줄이다.
+- 화면은 글자로만 보인다(링크 · HTML 없음): 로그인 화면(「비밀번호를 잊으셨나요?」 아래), 코드 단계 · 2단계 켜기(「인증 앱을 쓸 수 없나요?」 아래), 받은편지함 알림 메일의 마지막 줄.
+  정하지 않았으면 지금 글 그대로다(디자인 README 13단계). 잠긴 계정도 비밀번호 틀림과 같은 `AUTH_004` 라 같은 줄로 안내한다.
+
+### 받은편지함 알림 메일 (시스템 메일)
+
+- 서버가 대리 접근으로 그 직원의 받은편지함에 넣는다(`Email/import`).
+  - 안 읽음으로, 받은 시각은 지금이다.
+  - 필터 · 스팸 판정을 거치지 않고, 실시간 알림이 간다.
+- 보낸 사람은 `ARA SYSTEM <postmaster@<MAIL_DOMAIN>>` 이다. 엔진 안이라 SPF · DKIM 과 상관없다.
+- 보내는 때
+  - 운영 도구의 비밀번호 재설정 · 2단계 해제
+  - 위험 파일 판정 — 11단계에서 미룬 것. 그 파일을 올린 직원에게 보낸다.
+- 넣기에 실패해도 원래 일은 성공으로 둔다(warn 로그).
+- 본문은 짧은 HTML(보내는 정화 허용 목록 안) + 같은 글의 텍스트다. 제목 · 문구는 디자인 README 13단계를 그대로 쓴다.
+- **링크를 넣지 않는다** — 할 일은 메뉴 경로를 글로 적는다(「웹메일 › 설정 › 계정 › 앱 비밀번호」 등). 직원에게 "회사 보안 알림에는 링크가 없다"는 습관을 주어 링크 달린 피싱 메일이 눈에 띄게 한다.
+- 위험 파일 알림은 파일마다 한 번 — 위험 판정을 처음 기록할 때만 보낸다.
+
+### 운영 도구 (서버 안 명령)
+
+- 실행: `sudo docker exec -it <PROJECT_NAME>-backend node dist/cli/ops.js`. 운영 이미지에 들어 있다.
+  - 한국어 메뉴로 묻고, 바뀔 것을 보여 주고, y/N 으로 확인받은 뒤 실행한다.
+  - 엔진 관리 API(관리자 Basic — `MAIL_JMAP_URL`)와 우리 DB · 서비스를 함께 쓴다.
+- 처음에 묻는 것
+  - 운영자 이름 — 실행 기록에 남긴다.
+  - 관리자 비밀번호 — 저장하지 않는다. 화면에 보이지 않게 넣는다.
+- 실행 기록 표(`ops_audit_log`): 언제 · 누가 · 명령 · 대상 · 결과. 비밀은 남기지 않는다.
+- 명령
+
+| 명령 | 하는 일 |
+| --- | --- |
+| 입사 | 주소 · 이름 · 메일함 용량 → 엔진 계정(직원 역할) + 임시 비밀번호(무작위 — 한 번만 보여 줌) + 만료(첫 로그인 때 바꾸기) |
+| 비밀번호 재설정 | 임시 비밀번호 + 만료, 웹메일 세션 모두 끊기, 앱 비밀번호 지우기, 받은편지함 알림. 2단계는 그대로다(따로 해제) |
+| 2단계 해제 | 휴대폰 분실 — 엔진 OTP 지우기 + `enabledAt` 정리 + 받은편지함 알림 |
+| 잠금 | 퇴사 · 털림 — 엔진 `authenticate` 빼기, 웹메일 세션 모두 끊기. 묻고: 그 직원의 공개 링크 끊기, 받는 메일 넘기기(Sieve `redirect :copy`), 자동 응답. 메일은 계속 받는다 |
+| 잠금 풀기 | `authenticate` 되돌리기. 비밀번호 재설정을 함께 권한다 |
+| 퇴사 마무리 | 잠긴 계정만. 엔진 계정 지우기(메일 영구 삭제 — 주소를 다시 쳐서 확인) + 우리 DB 의 그 주소 행 정리 — 같은 주소를 다시 쓸 때 섞이지 않게 |
+| 링크 끊기 | 신고된 공개 링크 주소로 → `revoked_by = operator` |
+| 공용 주소 | MailingList 만들기 · 구성원 넣기 / 빼기 · 목록(구성원 받은편지함으로 복사) |
+| 현황 | 직원마다 잠금 · 2단계 · 앱 비밀번호 수 · 마지막 웹메일 로그인 · 메일함 사용량 |
+| 정책 · 설정 | 2단계 필수(켜기 · 시작일 · 예외), 문의 연락처 |
+
+- 차례가 있는 명령
+  - 비밀번호 재설정: 앱 비밀번호 지우기 · 알림 메일 넣기(대리 접근) → 엔진에 임시 비밀번호 + 만료 → 웹메일 세션 끊기. 만료 뒤에는 대리 접근 메서드가 막히기 때문이다. 엔진 바꾸기가 실패하면 넣은 알림 메일을 지운다.
+  - 잠금: 받는 메일 넘기기 · 자동 응답(대리 접근으로 Sieve)을 먼저 걸고 → `authenticate` 빼기 → 세션 끊기. 뺀 뒤에는 대리 접근이 막혀 Sieve 를 새로 걸 수 없다(이미 건 Sieve 는 계속 돈다).
+  - 퇴사 마무리: 엔진 계정을 지운 뒤 우리 DB 에서 그 주소의 행을 지운다 — 로그인 기록 · 앱 비밀번호 사용 · 2단계 설정 · 서명 · 설정 · 세션 · 사내 목록 기록 · 대용량 파일 · 링크. 실행 기록(`ops_audit_log`)은 남긴다.
+- 관리자 계정에서 대리 접근 권한(`impersonate`)을 빼므로(인프라 — mail/README) 도구가 직원의 메일함 · Sieve · 앱 비밀번호를 다룰 때는 웹메일과 같은 게이트웨이 대리 접근을 쓴다. 관리자 Basic 은 계정 관리 API(`x:Account` · `x:MailingList`)에만 쓴다.
+- **도구로 끊은 세션도 15초 안에 막힌다.** 세션 끊기는 DB 로 하고, 서버는 끊은 세션 기억을 15초마다 DB 에서 채운다(5절의 기억에 더한다).
+- 잠금은 도구로 한다. 엔진 관리 화면에서 `authenticate` 만 빼면 웹메일 세션이 남는다 — 갱신이 503 `MAIL_001` 을 내며 세션을 그대로 둔다(엔진의 대리 접근 403 을 설정 문제로 본다).
+
+### 에러 코드 (13단계에 더함)
+
+| 코드 | HTTP | 상황 | 문구 |
+| --- | --- | --- | --- |
+| `AUTH_010` | 403 | 제한된 세션(비밀번호 바꾸기 · 2단계 켜기 전)으로 다른 API | "먼저 비밀번호를 바꾸거나 2단계 인증을 켜 주세요." |
+
+### 휴지통 · 스팸 30일 · 메일 프로그램 연결
+
+- 휴지통 · 스팸메일함의 메일은 엔진이 지운다: 그 메일함에 들어간 날부터 30일, 매일 03:00 KST(setup). API 는 없고 화면 안내 줄만 둔다.
+- 메일 프로그램 연결 화면은 화면 상수(`MAIL_CLIENT_SETTINGS`)로만 그린다. API 는 없다. 2단계 인증 상태는 `GET /api/two-factor` 로 보고, 받지 못하면 켠 직원의 안내(앱 비밀번호 꼭)로 둔다.
+  - 앱 비밀번호 화면(5절)의 설정값 상자 아래에 이 화면으로 가는 바로가기를 둔다.
+  - 새 Outlook · 휴대폰 Outlook 앱은 메일을 Microsoft 클라우드를 거쳐 받으므로 권하지 않는다고 안내한다(회사가 허용하면 그 줄을 지운다).
+
+### 확장 때 옮길 것
+
+- 2단계 필수 정책 · 문의 연락처는 DB 라 그대로 맞다.
+- 끊은 세션 기억은 15초 DB 동기화라 인스턴스를 늘려도 15초 안에 맞는다.
+
+### 이 단계에서 하지 않는 것
+
+웹메일 관리자 화면(공통 기반 때), 비밀번호 스스로 재설정(복구 연락처 필요), 직원이 켜진 채 새 휴대폰으로 바꾸기(관리자의 「2단계 해제」로 한다),
+공용 주소로 보내기 · 공유 메일함(Group), 새 기기 로그인 알림 메일, 관리자 열람 기능, 주소 바꾸기, 모바일 앱.