# tdc114plus-auth 운영/커밋 정책

작성일: 2026-07-15
상태: v1.0

목적: `tdc114plus-auth` 공식 저장소의 운영 기준, 커밋 경계, 검증 기준, `tdc114plus` 앱 저장소와의 교차 작업 규칙을 고정한다.

관련 저장소:

- 앱 저장소: `https://gitea.hmac.kr/kevin/tdc114plus.git`
- auth 저장소: `https://gitea.hmac.kr/kevin/tdc114plus-auth.git`

관련 문서:

- `docs/00_policy_tdc114plus_auth_repo_2026-07-15.md`
- `docs/00_guide_tdc114plus_auth_broker_redirect_flow_2026-07-15.md`
- `docs/review_baron_sso_repo_commit_policy_2026-07-15.md`

## 1. 적용 범위

이 정책은 `tdc114plus-auth` 저장소의 아래 항목에 적용한다.

- 인증 중계 서버 본체 코드
- Baron SSO headless/login 연동 코드
- OIDC callback 처리
- JWKS 제공
- 앱 세션 발급/검증
- org-context proxy
- auth 서버 운영 문서
- auth 서버 테스트와 실행 스크립트

## 2. 역할 정의

`tdc114plus-auth`는 아래 책임을 가진 독립 서버다.

- 앱의 `link/init`, `link/poll` 요청 수신
- Baron SSO headless/link API 호출
- `client_assertion` 생성
- `login_challenge` 확보
- `redirectTo` 추적
- consent 처리
- authorization code 수신
- token exchange
- 앱 전용 session token 발급
- 조직도/직원 API proxy

즉, 이 저장소는 앱 UI 저장소가 아니라 보안/인증 책임을 가진 서버 저장소다.

## 3. 브랜치 정책

- `main`: 배포 가능한 기준 브랜치
- `feature/<topic>`: 기능 추가
- `fix/<topic>`: 버그 수정
- `ops/<topic>`: 운영 설정, 실행 절차, 문서, 환경 가이드
- `docs/<topic>`: 정책/가이드 문서 정리

예시:

- `feature/link-poll-session`
- `feature/org-context-proxy`
- `fix/oidc-callback-state`
- `ops/staging-env-guide`

## 4. 커밋 경계 정책

한 커밋에는 아래 중 한 가지 성격만 담는다.

1. 인증 기능 변경
2. 세션/보안 로직 변경
3. proxy/API 동작 변경
4. 테스트 추가/수정
5. 운영 문서/실행 스크립트 변경

권장 원칙:

- 기능 변경과 포맷 변경을 섞지 않는다.
- 리팩터링과 동작 변경을 가능하면 분리한다.
- 문서 개정만 있을 때는 문서 커밋으로 따로 남긴다.
- `.env.example` 변경은 실제 코드 변경과 강하게 연결될 때만 함께 커밋한다.

## 5. 커밋 메시지 규칙

권장 형식:

```text
type(scope): summary
```

예시:

```text
feat(auth): add Baron link poll completion handling
```

```text
fix(callback): validate state before token exchange
```

```text
feat(proxy): add org-context bearer session guard
```

```text
docs(ops): update staging auth server startup guide
```

## 6. 앱 저장소와의 교차 작업 규칙

앱 저장소와 auth 저장소를 함께 바꿔야 하는 경우에도 한 저장소에서 한 커밋만 만든다.

원칙:

- `tdc114plus` 앱 코드는 앱 저장소에서만 커밋한다.
- `tdc114plus-auth` 서버 코드는 auth 저장소에서만 커밋한다.
- 서로 연관된 변경이면 커밋 본문에 상대 저장소 커밋 해시를 남긴다.

예시:

```text
Related-App-Commit: abc1234
```

```text
Related-Auth-Commit: def5678
```

## 7. 보안/비밀정보 정책

절대 tracked commit에 넣지 않는 항목:

- private key
- public/private key 실제 파일
- 운영/개발 `.env`
- client secret
- session secret 실제 값
- org-context key/secret 실제 값
- 실사용 token
- 승인 완료 callback query 원문 로그 전체

허용 항목:

- `.env.example`
- 예시 placeholder
- 비식별화된 로그 예시
- 마스킹된 설정 예시

## 8. main 반영 전 최소 검증

`main` 반영 전 최소 확인 기준:

- 서버 기동 성공
- `/health` 응답 확인
- mock 또는 Baron mode 기준 핵심 auth 흐름 확인
- 변경 범위에 맞는 test 실행
- README 또는 관련 운영 문서 최신화 여부 확인

권장 검증 예:

```bash
go test ./...
```

```bash
go run ./cmd/server
```

실제 Baron 연동 변경이면 아래 중 최소 하나를 남긴다.

- 수동 검증 기록
- 로그 요약
- 관련 문서 링크

## 9. 운영 문서 정책

아래 내용이 바뀌면 문서를 함께 갱신한다.

- callback URL
- JWKS URI
- base URL
- proxy endpoint
- env 변수 이름/역할
- mock/baron 모드 동작 차이
- 앱이 의존하는 응답 필드

문서 우선순위:

1. auth 저장소 `README.md`
2. auth 저장소 `docs/`
3. 앱 저장소의 auth 연동 문서

## 10. 배포/운영 해석

- `main`은 배포 후보 기준으로 유지한다.
- 실험적 Baron 계약 검증은 feature 브랜치에서 먼저 진행한다.
- 운영 반영 전에는 개발용 IP 기반 URL보다 도메인 기반 URL을 우선 문서화한다.
- `114-auth.hmac.kr`에서 `114.hmac.kr`로 통합 논의가 생기면, 먼저 auth 저장소 문서를 갱신하고 이후 앱 저장소 설정을 맞춘다.

## 11. 현재 기준 결론

- `tdc114plus-auth`는 이미 공식 저장소가 존재하므로 생성 검토 단계는 종료됐다.
- 이제 필요한 것은 저장소 추가가 아니라 운영/커밋 규칙의 고정이다.
- 이후 auth 관련 서버 변경은 이 정책을 기준으로 저장소 분리, 커밋 분리, 검증 기록 분리를 유지한다.