sam-react-prod/claudedocs/api/[IMPL-2025-11-07] api-key-management.md

# API Key 관리 가이드

## 📋 개요

PHP 백엔드에서 발급하는 API Key의 안전한 관리 및 주기적 갱신 대응 방법

---

## 🔑 현재 API Key 정보

```yaml
개발용 API Key:
  키 값: 42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
  발급일: 2025-11-07
  용도: 개발 환경 고정 키
  갱신: 주기적으로 변동 가능
```

---

## 🔐 보안 원칙

### ✅ DO (반드시 해야 할 것)
- `.env.local`에만 실제 키 저장
- 서버 사이드 코드에서만 사용
- Git에 절대 커밋 금지
- 팀 공유 문서로 키 관리

### ❌ DON'T (절대 하지 말 것)
- 하드코딩 금지
- `NEXT_PUBLIC_` 접두사 사용 금지
- 브라우저 코드에서 사용 금지
- 공개 저장소에 업로드 금지

---

## 📁 파일 구성

### .env.local (실제 키 - Git 제외)
```env
# API Key (서버 사이드 전용 - 절대 공개 금지!)
# 개발용 고정 키 (주기적 갱신 예정)
# 발급일: 2025-11-07
# 갱신 필요 시: PHP 백엔드 팀에 새 키 요청
API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
```

### .env.example (템플릿 - Git 커밋 OK)
```env
# API Key (⚠️ 서버 사이드 전용 - 절대 공개 금지!)
# 개발팀 공유: 팀 내부 문서에서 키 값 확인
# 주기적 갱신: PHP 백엔드 팀에서 새 키 발급 시 업데이트 필요
API_KEY=your-secret-api-key-here
```

### .gitignore 확인
```bash
# 라인 100-101에 이미 포함됨
.env.local
.env*.local
```

---

## 🔄 API Key 갱신 프로세스

### 1️⃣ PHP 팀에서 새 키 발급
```
PHP 백엔드 팀 → 새 API Key 발급
                ↓
         팀 공유 문서 업데이트
```

### 2️⃣ 로컬 개발 환경 업데이트
```bash
# .env.local 파일 열기
vi .env.local

# 또는
code .env.local

# API_KEY 값만 변경
API_KEY=새로운키값여기에입력

# 개발 서버 재시작
npm run dev
```

### 3️⃣ 프로덕션 환경 업데이트

#### Vercel 배포
```bash
# CLI로 업데이트
vercel env add API_KEY production

# 또는 대시보드에서
# Settings → Environment Variables → API_KEY 편집
```

#### AWS/기타 환경
```bash
# 환경 변수 업데이트
export API_KEY=새로운키값

# 또는 배포 설정에서 환경 변수 수정
```

### 4️⃣ 검증
```bash
# 개발 서버 시작 시 자동으로 검증됨
npm run dev

# 콘솔 출력 확인:
# 🔐 API Key Configuration:
#   ├─ Configured: ✅
#   ├─ Valid Format: ✅
#   ├─ Masked Key: 42Jf********************dk1a
#   └─ Length: 48 chars
```

---

## 🛠️ API Key 검증 유틸리티

### 자동 검증 기능
```typescript
// lib/api/auth/api-key-validator.ts
import { apiKeyValidator } from '@/lib/api/auth/api-key-validator';

// 개발 서버 시작 시 자동 실행
console.log(apiKeyValidator.getDebugInfo());

// 출력 예시:
// API Key Status:
//   ├─ Configured: ✅
//   ├─ Valid Format: ✅
//   ├─ Masked Key: 42Jf********************dk1a
//   └─ Length: 48 chars
```

### 수동 검증
```typescript
import { apiKeyValidator } from '@/lib/api/auth/api-key-validator';

// API Key 존재 확인
if (!apiKeyValidator.isConfigured()) {
  console.error('API Key not configured!');
}

// 형식 검증
if (!apiKeyValidator.isValid()) {
  console.error('Invalid API Key format!');
}

// 디버그 정보 출력
console.log(apiKeyValidator.getDebugInfo());
```

---

## 📊 사용 예시

### 서버 사이드 (Next.js API Route)
```typescript
// app/api/sync/route.ts
import { createApiKeyClient } from '@/lib/api/auth/api-key-client';

export async function GET() {
  try {
    // 환경 변수에서 자동으로 키를 가져옴
    const client = createApiKeyClient();

    const data = await client.fetchData('/api/external-data');

    return Response.json({ success: true, data });
  } catch (error) {
    console.error('API request failed:', error);
    return Response.json(
      { error: 'Failed to fetch data' },
      { status: 500 }
    );
  }
}
```

### 백그라운드 스크립트
```typescript
// scripts/sync-data.ts
import { createApiKeyClient } from '@/lib/api/auth/api-key-client';
import { apiKeyValidator } from '@/lib/api/auth/api-key-validator';

async function syncData() {
  // 1. 환경 변수 확인
  console.log(apiKeyValidator.getDebugInfo());

  if (!apiKeyValidator.isValid()) {
    throw new Error('Invalid API Key configuration');
  }

  // 2. API 요청
  const client = createApiKeyClient();
  const data = await client.fetchData('/api/sync-endpoint');

  console.log('Sync completed:', data);
}

syncData().catch(console.error);
```

---

## ⚠️ 에러 처리

### API Key 미설정
```
❌ API_KEY is not configured!
📝 Please check:
   1. .env.local file exists
   2. API_KEY is set correctly
   3. Restart development server (npm run dev)

💡 Contact backend team if you need a new API key.
```

**해결 방법:**
1. `.env.local` 파일 생성 확인
2. `API_KEY=실제키값` 입력
3. `npm run dev` 재시작

### API Key 형식 오류
```
❌ Invalid API Key format!
   - Minimum 32 characters required
   - Only alphanumeric characters allowed
```

**해결 방법:**
1. PHP 팀에서 발급받은 키 확인
2. 복사 시 공백/줄바꿈 없는지 확인
3. 정확한 키 값 재입력

---

## 🔍 만료 경고 (선택사항)

### 만료 체크 기능
```typescript
// lib/api/auth/key-expiry-check.ts
import { apiKeyValidator } from './api-key-validator';

// API Key 발급일
const issuedDate = new Date('2025-11-07');

// 90일 유효기간으로 체크
const status = apiKeyValidator.checkExpiry(issuedDate, 90);

console.log(status.message);
// ✅ API Key valid (75 days left)
// ⚠️ API Key expiring in 10 days
// 🔴 API Key expired! Contact backend team.

if (status.isExpiring) {
  console.warn('⚠️ Please contact backend team for new API key!');
}
```

---

## 📚 체크리스트

### 초기 설정
- [ ] `.env.local` 파일 생성
- [ ] `API_KEY` 값 입력
- [ ] `.gitignore`에 `.env.local` 포함 확인
- [ ] 개발 서버 시작 후 검증 확인

### 키 갱신 시
- [ ] PHP 팀에서 새 키 수령
- [ ] `.env.local` 업데이트
- [ ] 로컬 개발 서버 재시작
- [ ] 검증 로그 확인
- [ ] 프로덕션 환경 변수 업데이트

### 보안 점검
- [ ] Git에 `.env.local` 커밋 안됨
- [ ] 브라우저 코드에서 사용 안함
- [ ] `NEXT_PUBLIC_` 접두사 없음
- [ ] 팀 공유 문서에 키 기록

---

## 🚀 다음 단계

API Key 설정 완료 후:
1. `createApiKeyClient()` 사용하여 API 요청
2. 서버 사이드 코드에서만 호출
3. 에러 발생 시 검증 로그 확인
4. 주기적으로 만료 시간 체크 (선택)

---

## 📞 문의

- **API Key 발급**: PHP 백엔드 팀
- **기술 지원**: 프론트엔드 팀
- **보안 문제**: DevOps/보안 팀

---

## 관련 파일

### 프론트엔드
- `src/lib/api/auth/api-key-client.ts` - API Key 클라이언트
- `src/lib/api/auth/api-key-validator.ts` - API Key 검증 유틸리티
- `src/app/api/sync/route.ts` - 서버 사이드 API Route 예시

### 설정 파일
- `.env.local` - 환경 변수 (API_KEY 저장)
- `.env.example` - 환경 변수 템플릿
- `.gitignore` - Git 제외 설정