vpd-permission-poc/docs/design/424-spring-boot-vpd-backoffice/fn-issueToken.md

함수 설계서: issueToken (#424)

부모 설계서: ./README.md · 상태: Draft 작성: [AI] Architect · 구현: BearerTokenService.issueToken · 테스트: BearerTokenServiceTest

1. 시그니처

IssuedToken issueToken(TokenIssueCommand command)

2. 책임 (단일 책임, 1줄)

활성 사용자에게 새 Bearer Token을 발급하고 DB에는 원문이 아닌 hash와 prefix만 저장한다.

3. 입력

파라미터	타입	제약/검증	설명
command.userId	long	활성 사용자여야 함	토큰 소유 사용자
command.expiresAt	OffsetDateTime	현재 시각 이후, 최대 정책 기간 이내	만료 시각
command.description	String	200자 이하	운영자 식별 설명

4. 출력

• 반환: IssuedToken
  • keyId: 저장된 key id
  • prefix: 화면 식별용 prefix
  • plainToken: 발급 직후 한 번만 보여줄 원문 token
  • expiresAt: 만료 시각
• 부수효과: CB_AGENT_BEARER_KEY insert, audit insert

5. 동작 / 알고리즘

1. userId로 사용자를 조회하고 active_yn = 'Y'인지 확인한다.
2. 만료일이 현재 시각 이후인지 확인한다.
3. 정책상 최대 유효 기간을 넘으면 실패한다.
4. vpd_live_ prefix와 256bit 이상 난수 body를 생성한다.
5. 원문 token을 조합한다.
6. 기존 ORDS 패키지의 STANDARD_HASH(..., 'SHA256') 검증과 호환되는 SHA-256 hash를 만든다.
7. key_prefix, key_hash, expires_at, created_by를 저장한다.
8. audit log를 저장한다.
9. 원문 token을 포함한 IssuedToken을 반환한다.

6. 에러 & 실패 모드

조건	처리	반환/예외
사용자가 없음	발급 중단	UserNotFoundException
비활성 사용자	발급 중단	InactiveUserException
만료일이 과거	발급 중단	InvalidTokenExpiryException
DB 저장 실패	transaction rollback	DataAccessException

7. 엣지케이스

• 같은 사용자에게 여러 token 발급은 허용한다.
• prefix는 식별용이므로 중복 가능성을 낮추되, 인증 판단에는 hash만 사용한다.
• 원문 token은 log, audit, exception message에 포함하지 않는다.

8. 복잡도 / 성능

• 시간 복잡도는 O(1)이다.
• 호출 빈도는 낮고 운영자 작업 단위다.
• 난수 생성은 SecureRandom 또는 JDK 보안 API를 사용한다.

9. 의존성

• UserMapper
• BearerTokenMapper
• AuditService
• TokenHasher
• Clock

10. 테스트 케이스

• 정상: 활성 사용자와 미래 만료일 입력 시 원문 token과 저장 id 반환
• 정상: 저장된 값에 원문 token이 포함되지 않음
• 실패: 비활성 사용자 입력 시 예외
• 실패: 과거 만료일 입력 시 예외
• 정상: cb_hr_key hash가 Oracle STANDARD_HASH('cb_hr_key', 'SHA256')와 같은 값

11. 추적성

• 인수조건: #424의 "Bearer Token은 발급 시 원문을 한 번만 보여주고 DB에는 hash, prefix, 만료/회수 상태만 저장한다."
• 관련 ADR: 없음