docs: 12단계 계정 보안 — 계약 5절 · 디자인 보드 넷 · README #9

Merged

ttipo merged 6 commits from feat/mail-account-security into main 2026-11-02 15:52:33 +09:00

Conversation 0 Commits 6 Files Changed 175

+22972 -352

ttipo commented 2026-10-31 17:56:55 +09:00

Owner

Copy Link

Copy Source

무엇을 · 왜

확인 방법

영향 범위

• backend
• frontend
• flutter
• docker / 인프라
• 규칙 문서(.claude/)

공유 계약(에러 코드 · 응답 포맷 · 페이지네이션 · API 규약)을 바꿨다면
세 스택에 미치는 영향을 아래에 구체적으로 적어 주세요.

체크리스트

• 린트/분석 통과 (Warning 0) · 변경 영역 테스트 통과
• 주석 한국어, 매직 넘버·하드코딩 문자열 없음
• 사용자 노출 실패는 모두 에러 코드와 함께 처리 (BusinessException / error.code 분기)
• 에러 코드를 바꿨다면 npm run sync:error-codes 실행 후 생성 파일까지 커밋
• 민감정보 미커밋 (*.example 값은 placeholder)
• 로그에 비밀번호·토큰·요청 본문 전체가 남지 않음

## 무엇을 · 왜 <!-- 무엇을 바꿨고 왜 필요한지 적습니다. "무엇을"은 diff 가 말해주므로 "왜"에 비중을 둡니다. --> ## 확인 방법 <!-- 리뷰어가 동작을 확인할 수 있는 절차나 명령을 적습니다. --> ## 영향 범위 - [ ] backend - [ ] frontend - [ ] flutter - [ ] docker / 인프라 - [ ] 규칙 문서(.claude/) > **공유 계약(에러 코드 · 응답 포맷 · 페이지네이션 · API 규약)을 바꿨다면** > 세 스택에 미치는 영향을 아래에 구체적으로 적어 주세요. ## 체크리스트 <!-- 자세한 항목은 .claude/rules/checklist.md 참조 --> - [ ] 린트/분석 통과 (Warning 0) · 변경 영역 테스트 통과 - [ ] 주석 한국어, 매직 넘버·하드코딩 문자열 없음 - [ ] 사용자 노출 실패는 모두 에러 코드와 함께 처리 (`BusinessException` / `error.code` 분기) - [ ] 에러 코드를 바꿨다면 `npm run sync:error-codes` 실행 후 생성 파일까지 커밋 - [ ] 민감정보 미커밋 (`*.example` 값은 placeholder) - [ ] 로그에 비밀번호·토큰·요청 본문 전체가 남지 않음

ttipo added 6 commits 2026-10-31 17:56:55 +09:00

docs: 12단계 계정 보안 — 계약 5절 · 디자인 보드 넷 · README ... adb992e6d8

2단계 인증(인증 앱 TOTP) · 앱 비밀번호 · 로그인 기록을 엔진(Stalwart 0.16.27) 실험 결과에 맞춰 정했다.
엔진이 코드 확인 · 메일 프로그램 막기 · 앱 비밀번호를 맡고, 서버는 첫 코드 확인 · 다시 쓰기 막기 · 실패 한도 · 기록을 맡는다.
사용자 결정(2026-10-31): 비밀번호를 바꾸면 앱 비밀번호도 지우고, 끊은 세션은 바로 막는다.

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

feat(backend): 12단계 계정 보안 — 2단계 로그인 · 2FA · 앱 비밀번호 · 세션 끊기 · 로그인 기록 · 엔진 웹훅 ... f9e3b1c57a

엔진(Stalwart 0.16.27)의 TOTP 와 앱 비밀번호를 쓰되, 엔진이 하지 않는 것을 서버가 맡는다.
- 등록 때 첫 코드 확인, 성공에 쓴 코드 2분 막기(확인 중인 같은 코드도), 코드 실패 한도(15분 5 · 24시간 20)
- 웹메일 로그인 · 비밀번호 바꾸기에서 앱 비밀번호 모양 거절, 앱 비밀번호는 메일 프로그램 권한만
- 엔진 Basic 의 402 를 장애(MAIL_001)로 다루던 것을 고쳐 코드 단계로 — 402 면 정식 주소로 한도 · 기록
- 비밀번호를 바꾸면 앱 비밀번호도 지우고, 끊은 세션은 액세스 토큰의 sid 로 바로 막는다
- 메일 프로그램 로그인은 엔진 웹훅(소켓 주소 · HMAC · 내용 지문 · 1,000행씩)으로 받아 90일 남긴다
- 요청 대상에 날 \ · # 가 있으면 라우팅 전에 400 — Express 가 이를 다시 읽어 앞단이 닫은 경로가 열렸다
에러 코드 AUTH_006 ~ AUTH_009 와 웹 · 앱 사전, 마이그레이션 AddAccountSecurity 를 함께 넣었다.

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

feat(frontend): 12단계 계정 보안 화면 — 로그인 코드 단계 · 2단계 인증 · 앱 비밀번호 · 로그인 기록 ... c31442e639

로그인은 비밀번호가 맞고 2단계를 켠 직원만 코드 단계로 간다. 설정 › 계정에 2단계 인증 · 앱 비밀번호 · 로그인 기록을 더하고,
비밀번호 화면에 2단계를 켠 직원의 코드 칸을 둔다.
비밀(코드 단계의 비밀번호 · 2단계 키 · 앱 비밀번호 값)은 화면 메모리에만 두고, 세션이 바뀌면 그 창을 모두 닫는다 —
12단계부터 다른 기기의 로그아웃이 이 세션을 바로 끊는다. 비밀이 드는 요청은 Pinia 액션 밖에서 보낸다(devtools 기록).
QR 은 uqr 0.1.3(MIT · 의존성 없음 — 2단계 인증 화면 청크에만)으로 SVG 를 그린다(v-html 없음).

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

feat(docker): 12단계 계정 보안 — 엔진 웹훅 · /api/internal 닫기 · 요청 대상 400 ... d1ef0da488

메일 프로그램(IMAP · SMTP) 로그인 기록을 엔진 웹훅으로 받는다.
- 루트 env MAIL_WEBHOOK_SECRET(setup · backend 공용, 운영 필수)과 backend 의 APP_NETWORK_SUBNET
- setup 이 엔진 웹훅을 맞추고(표시 머리글 — 소금 + 키 지문) 서명한 빈 묶음으로 받는 곳을 확인한다
  키를 바꾼 실행 · 게이트웨이 OTP · 테스트 직원의 402 를 따로 다룬다
- nginx 두 server 가 /api/internal/ 을 닫고, 요청 대상의 날 \(경로) · # · 0x80 이상은 location 전에 400
  Express 가 이런 대상을 다시 읽어 닫은 경로(/api/internal · /api/health)가 백엔드에서 열렸다(2026-10-31 리뷰)
- CI "닫는 경로 시험"(두 server × 세 경로의 변형) · 지시어만 세는 정적 검사
- mail/README: 웹훅 · 12단계 전부터 운영 중인 서버를 올리는 차례 · 휴대폰을 잃은 직원(관리 API 명령)
엔진 DNS 가 Custom(운영)이어도 웹훅은 backend 를 푼다 — 메일 컨테이너가 도커 DNS 를 쓴다(개발에서 확인).

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

docs: 12단계 계약 · README — 구현하며 정한 것 ... 9a72ce91e1

계약 5절에 구현과 리뷰에서 정한 것을 반영했다 — 같은 코드가 확인 중이어도 AUTH_006, 402 는 정식 주소 기준,
웹훅은 내용 지문 · DB 에 넣은 뒤 200 · 1,000행씩, 요청 대상의 날 \ · # 는 400, 끊은 세션의 실시간 알림 닫기 등.
디자인 README 12단계 절에 QR 160 · 결과 창 [복사] 44 · 10분 · 코드 단계 오류 자리 · 코드 2분 다시 받지 않음을 더했다.

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

docs(rules): 12단계 부품 — 계정 보안 · 요청 대상 검사 · 엔진 웹훅 · 스킬 표 · env ... 781ffb2e16

security: 2단계 인증 · 앱 비밀번호 · 끊은 세션 바로 막기 · 엔진이 부르는 길(세 겹) · 요청 대상의 날 \ · #.
nestjs · vue3: 골격 표에 계정 보안 행, 확장 때 옮길 메모리 상태, 엔진 Basic 402 는 장애가 아니다.
docker · env-structure · checklist: MAIL_WEBHOOK_SECRET · /api/internal 닫기 · 닫는 경로 시험 · setup 의 웹훅.

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

ttipo merged commit 781ffb2e16 into main 2026-11-02 15:52:33 +09:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

ttipo

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ttipo/arasystem#9