doclib 인증 모듈 리팩토링 계획 및 실행 결과

대상 브랜치: main시작 기준 커밋: 70939cb

1. 목적

로그인, 세션 확인, 비밀번호 변경, 현재 사용자 조회, 보호 API의 권한 검사를 하나의 인증 기능으로 묶었다. 이전에는 클라이언트 컨텍스트·관리자 비밀번호 화면·서버 인증 라우트·비밀번호 유틸리티가 서로 다른 공용 폴더에 분산되어 있었다. 이번 변경은 기존 HTTP 경로와 쿠키 정책을 유지하면서 인증 관련 코드를 전용 모듈로 옮기는 것을 목표로 했다.

인증 모듈은 사용자 인증 상태를 제공하고 세션 수명주기를 관리한다. 게시판·첨부파일·관리자 화면은 인증 모듈의 공개 API를 통해서만 현재 사용자와 로그인 상태를 사용한다.

2. 적용 구조

client/src/features/auth/
  api/auth-api.ts
  components/PasswordChangeModal.tsx
  context/AuthContext.tsx
  validation/password-rules.ts
  validation/password-rules.test.ts
  types.ts
  index.ts

server/features/auth/
  index.ts
  password.ts

영역	적용 내용	호환성
클라이언트 API	/api/auth/me, 로그인, 로그아웃, 비밀번호 변경 HTTP 호출을 auth-api.ts로 분리	API 경로와 오류 메시지를 유지
클라이언트 상태	AuthProvider와 useAuth를 features/auth/context로 이동	기존 contexts/AuthContext.tsx는 재내보내기로 유지
인증 화면	비밀번호 변경 모달과 입력 검증 규칙을 인증 기능이 소유	관리자 화면은 @/features/auth의 공개 export를 사용
서버 인증	로그인·세션·쿠키·권한 미들웨어를 server/features/auth로 이동	쿠키 이름, TTL, SameSite 및 /api/auth/* 엔드포인트를 유지
서버 암호화	암호 해시·검증 유틸리티를 인증 기능 하위로 이동	DB 초기화와 로그인 검증 호출 경로를 갱신

3. 의존 방향

클라이언트의 페이지와 공용 셸은 @/features/auth에서 AuthProvider 및 useAuth를 가져온다. 인증 모듈 내부에서는 Context가 화면 상태만 보유하고, 네트워크 통신은 api/auth-api.ts가 담당한다. 이 구분으로 로그인 화면이나 비밀번호 변경 모달이 세션 HTTP 세부 구현을 직접 다루지 않는다.

서버의 index.ts와 Archive API는 server/features/auth에서 인증 라우트 등록과 requireAuth 미들웨어를 가져온다. 세션 서명·쿠키 처리·사용자 조회는 인증 모듈 안에 남아, 인증 정책을 변경할 때 관련 파일을 한 경계 안에서 찾을 수 있다.1 2

4. 검증 결과

검증 항목	결과	비고
TypeScript 검사	통과	pnpm check 성공
프로덕션 빌드	통과	Vite 클라이언트 빌드와 Node 서버 번들 성공
결정적 단위 테스트	37개 통과, 2개 스킵	인증 쿠키·암호 해시·비밀번호 규칙 테스트 포함
외부 연동 테스트	2개 보류	ARCHIVE_API_KEY 및 Cloudflare R2 환경변수가 현재 검증 환경에 없음

5. 후속 규칙

새 인증 기능은 features/auth에 화면·상태·HTTP API를 함께 둔다. 권한이 필요한 다른 기능은 인증 Context의 공개 Hook을 사용하고, 인증 모듈 내부 구현이나 서버 쿠키 처리에 직접 의존하지 않는다. 향후 SSO, MFA, 비밀번호 재설정, 세션 갱신을 추가할 때도 같은 모듈을 확장한다.

References