docs(auth): document official auth repo policy

docs/00_policy_tdc114plus_auth_operations_2026-07-15.md

@@ -0,0 +1,202 @@
+# 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 관련 서버 변경은 이 정책을 기준으로 저장소 분리, 커밋 분리, 검증 기록 분리를 유지한다.