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

# tdc114plus-auth 저장소 운영 정책

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

목적: `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` 저장소 안에도 흡수하지 않는다.
- 최종 배포 기준에서도 `tdc114plus-auth`는 독립 배포 단위로 유지한다.
- 다만 현재 로컬 개발에 쓰는 `baron-sso-tdc114plus-api` worktree는 최종 배포 필수 구성으로 보지 않는다.
- 최종 운영 구조는 Baron SSO 원본 `staging` 연동 안정화 후 Baron SSO 원본 `production` 연동으로 승격하는 방향을 기본값으로 삼는다.

공식 저장소:

```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 경로를 참조하는 보조 도구로 유지할 수 있지만, 서버 구현 본체는 별도 저장소에 있어야 한다.

## 8-A. 로컬 Baron worktree와의 관계

현재 개발 과정에서는 아래 세 축이 함께 보일 수 있다.

- `tdc114plus`
- `tdc114plus-auth`
- `baron-sso-tdc114plus-api`

하지만 이 중 최종 배포 직접 대상은 아래 두 축으로 본다.

- `tdc114plus`
- `tdc114plus-auth`

정리 원칙:

- `baron-sso-tdc114plus-api`는 개발 중 API 확인, 임시 연동, 로컬 재현을 위한 worktree로 본다.
- 배포 직전에는 `tdc114plus-auth`가 어떤 기능을 계속 직접 수행해야 하는지와, 어떤 기능이 Baron SSO 원본 `staging/prod` 의존으로 남는지를 명확히 분리해야 한다.
- 로컬 Baron worktree가 꺼져도 배포 구조 자체에는 영향이 없도록 정리하는 것이 목표다.

## 9. 최종 판단

- `tdc114plus-auth`는 별도 저장소가 필요한 독립 서비스다.
- 이 저장소 분리는 선택이 아니라 사실상 운영 안정성을 위한 기본 구조로 보는 편이 맞다.
- 앱 저장소에는 연동 문서와 실행 보조 스크립트만 두고, 서버 코드/배포/보안 자산은 `tdc114plus-auth` 저장소에서 관리한다.