tdc114plus/docs/00_policy_tdc114plus_auth_repo_2026-07-15.md

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 저장소 안에도 흡수하지 않는다.

공식 저장소:

https://gitea.hmac.kr/kevin/tdc114plus-auth.git

기본 브랜치:

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

커밋 예시:

feat(auth): add Baron headless link init flow

fix(session): handle expired poll response consistently

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 저장소에서 관리한다.