86 lines
3.1 KiB
Markdown
86 lines
3.1 KiB
Markdown
# 함수 설계서: `issueToken` (#424)
|
|
|
|
> **부모 설계서**: ./README.md · **상태**: Draft
|
|
> **작성**: [AI] Architect · **구현**: `BearerTokenService.issueToken` · **테스트**: `BearerTokenServiceTest`
|
|
|
|
## 1. 시그니처
|
|
|
|
```java
|
|
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: 없음
|