docs(auth): document official auth repo policy

docs/00_policy_tdc114plus_auth_repo_2026-07-15.md

@@ -0,0 +1,193 @@
+# tdc114plus-auth 저장소 운영 정책
+
+작성일: 2026-07-15
+상태: v1.0
+
+목적: `tdc114plus-auth` 중계서버의 공식 Gitea 저장소 위치와 저장소 경계 운영 기준을 고정한다.
+
+관련 문서:
+
+- `docs/00_guide_tdc114plus_auth_broker_redirect_flow_2026-07-15.md`
+- `docs/00_policy_tdc114plus_development_2026-07-02.md`
+- `docs/review_baron_sso_repo_commit_policy_2026-07-15.md`
+
+## 1. 결론
+
+- `tdc114plus-auth`는 별도 Gitea 저장소로 관리한다.
+- `tdc114plus` 앱 저장소 안에 서버 본체 코드를 함께 두지 않는다.
+- `baron-sso` 저장소 안에도 흡수하지 않는다.
+
+공식 저장소:
+
+```text
+https://gitea.hmac.kr/kevin/tdc114plus-auth.git
+```
+
+기본 브랜치:
+
+```text
+main
+```
+
+현재 확인 기준:
+
+- 로컬 worktree: `/home/ubuntu/workspace/tdc114plus-auth`
+- 원격 `origin`: `https://gitea.hmac.kr/kevin/tdc114plus-auth.git`
+- 최근 확인 커밋: `2bc25d1 Add org context proxy`
+
+## 2. 왜 별도 저장소가 필요한가
+
+`tdc114plus-auth`는 단순 보조 스크립트가 아니라 독립 실행 서버다.
+
+현재 책임:
+
+- 앱의 `link/init`, `link/poll` 요청 수신
+- Baron SSO headless API 호출
+- `client_assertion` 생성
+- `login_challenge` 확보
+- `redirectTo` 추적
+- consent 처리
+- authorization code 수신
+- token exchange
+- 앱용 session token 발급
+- 직원/조직 API 중계
+
+즉, 이 서버는 Flutter 앱과도 다르고 Baron SSO 본체와도 다른 별도 배포 단위다.
+
+## 3. 저장소를 분리해야 하는 이유
+
+### 3.1 보안 경계 분리
+
+- 중계서버는 private key, session secret, OIDC 연계 설정, 외부 API credential을 다룬다.
+- 이런 값과 로직은 모바일 앱 저장소와 분리하는 편이 안전하다.
+- 앱 저장소에는 공개 가능한 설정과 실행 보조 스크립트만 남긴다.
+
+### 3.2 커밋 경계 분리
+
+- 앱 UI 변경과 중계서버 인증 로직 변경은 한 커밋으로 섞지 않는다.
+- 중계서버 장애 대응, 인증 예외 처리, API 응답 포맷 수정은 서버 커밋으로 따로 추적해야 한다.
+
+### 3.3 배포 경계 분리
+
+- 앱 배포와 중계서버 배포 시점은 다를 수 있다.
+- 서버는 긴급 핫픽스나 설정 변경이 앱 업데이트 없이도 필요할 수 있다.
+- 따라서 저장소와 배포 파이프라인도 분리하는 편이 낫다.
+
+### 3.4 권한 분리
+
+- 앱 개발자와 서버 운영자의 접근 권한이 달라질 수 있다.
+- 별도 저장소로 두면 읽기/쓰기 권한을 역할별로 나누기 쉽다.
+
+### 3.5 운영 이력 분리
+
+- 로그인 실패, consent 예외, token exchange 장애, org-context 중계 이슈는 앱 이슈와 성격이 다르다.
+- 서버 단위 이력, 태그, 릴리스 노트를 따로 관리해야 추적이 수월하다.
+
+## 4. 저장소별 책임 경계
+
+### 4.1 `tdc114plus` 저장소에 두는 것
+
+- Flutter 앱 코드
+- 앱 정책 문서
+- 앱 테스트 코드
+- 앱 실행/검증 스크립트
+- `tdc114plus-auth` 실행 방법과 연동 절차 문서
+
+### 4.2 `tdc114plus-auth` 저장소에 두는 것
+
+- HTTP server 본체
+- auth handler
+- Baron SSO client
+- consent 처리 로직
+- token exchange 로직
+- app session 발급/검증 로직
+- org-context proxy 또는 중계 로직
+- 서버 전용 테스트
+- 서버 전용 운영 문서
+
+### 4.3 `baron-sso` 저장소에 두는 것
+
+- Baron SSO 공식 backend/orgFront/userFront 코드
+- `tdc114plus-auth`가 소비해야 하는 공식 API 변경
+- Baron SSO 본체 정책 변경
+
+## 5. 금지 원칙
+
+- `tdc114plus-auth` 서버 코드를 `tdc114plus` 앱 저장소로 복사 반입하지 않는다.
+- private key, secret, 운영용 credential을 tracked 파일로 커밋하지 않는다.
+- 앱 저장소와 중계서버 저장소에 같은 서버 코드를 중복 보관하지 않는다.
+- 앱 커밋 하나에 서버 본체 코드 변경을 함께 넣지 않는다.
+
+## 6. 브랜치 및 커밋 정책
+
+브랜치 예시:
+
+- `main`
+- `feature/link-init-poll`
+- `feature/oidc-callback`
+- `fix/consent-redirect`
+- `ops/staging-config`
+
+커밋 예시:
+
+```text
+feat(auth): add Baron headless link init flow
+```
+
+```text
+fix(session): handle expired poll response consistently
+```
+
+```text
+ops(staging): adjust auth broker env defaults
+```
+
+앱 저장소와 함께 작업한 경우:
+
+- 앱 커밋 본문에 `Related-Auth-Commit: <hash>` 기록
+- auth 저장소 커밋 본문에 `Related-App-Commit: <hash>` 기록
+
+## 7. 현재 저장소 기준 최소 유지 항목
+
+현재 저장소에서 유지해야 할 기본 항목:
+
+- `README.md`
+- `.gitignore`
+- `.env.example`
+- `cmd/server/` 또는 동등한 진입점
+- `internal/` 또는 `pkg/` 구조
+- `secrets/`는 예시 파일만 tracked, 실제 키는 비추적
+- 배포/실행 방법 문서
+
+권장:
+
+- `docs/`
+- `Makefile` 또는 표준 실행 스크립트
+- health check endpoint
+- staging/prod 설정 가이드
+
+현재 확인된 기본 구성:
+
+- `cmd/server/`
+- `docs/`
+- `.env.example`
+- `.gitignore`
+- `go.mod`
+- `README.md`
+
+## 8. 현재 앱 저장소에서의 역할
+
+현재 앱 저장소는 `tdc114plus-auth`를 직접 소유하지 않고 아래 역할만 가진다.
+
+- 중계서버 필요성 문서화
+- 중계서버 실행 보조 스크립트 유지
+- 연동 주소, 포트, 점검 절차 문서화
+- 앱과 중계서버 간 계약 확인
+
+예를 들어 `scripts/start-auth-server.sh`는 `tdc114plus-auth` worktree 경로를 참조하는 보조 도구로 유지할 수 있지만, 서버 구현 본체는 별도 저장소에 있어야 한다.
+
+## 9. 최종 판단
+
+- `tdc114plus-auth`는 별도 저장소가 필요한 독립 서비스다.
+- 이 저장소 분리는 선택이 아니라 사실상 운영 안정성을 위한 기본 구조로 보는 편이 맞다.
+- 앱 저장소에는 연동 문서와 실행 보조 스크립트만 두고, 서버 코드/배포/보안 자산은 `tdc114plus-auth` 저장소에서 관리한다.