kevin/tdc114plus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(auth): document official auth repo policy

Browse Source
This commit is contained in:
Codex
2026-07-15 10:58:31 +09:00
parent d5edaf0a4d
commit 57caca8dc8
3 changed files with 441 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/00_policy_tdc114plus_auth_operations_2026-07-15.md
+202
View File
@@ -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 관련 서버 변경은 이 정책을 기준으로 저장소 분리, 커밋 분리, 검증 기록 분리를 유지한다.
docs/00_policy_tdc114plus_auth_repo_2026-07-15.md
+193
View File
@@ -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` 저장소에서 관리한다.
docs/README.md
+46
View File
@@ -0,0 +1,46 @@
# tdc114plus 문서 색인
이 문서는 `docs` 바로 아래에 있는 Markdown 파일의 첫 줄 제목을 모아, 개발자가 각 문서의 내용을 빠르게 파악할 수 있도록 정리한 색인입니다.
파일명 규칙:
- `00_`: 개발 진행 전 반드시 먼저 검토해야 하는 핵심 문서
- `policy_`: 정책/원칙 문서
- `contract_`: API 계약 문서
- `checklist_`: 점검 체크리스트 문서
- `runtime_`: 실행/운영 절차 문서
- `dev_env_`: 개발환경 구성 문서
- `guide_`: 가이드/참고 문서
- `scenario_`: 시나리오 문서
- `review_`: 검토 결과 문서
| 파일 | 첫 줄 제목 |
| --- | --- |
| [policy_android_app_install_execution_2026-07-06.md](policy_android_app_install_execution_2026-07-06.md) | Android 앱 설치/실행 재발 방지 정책 |
| [scenario_android_emulator_device_integration_test_2026-07-03.md](scenario_android_emulator_device_integration_test_2026-07-03.md) | Android target 통합테스트 진행 시나리오 |
| [policy_android_studio_wsl_adb_2026-07-03.md](policy_android_studio_wsl_adb_2026-07-03.md) | Android Studio / WSL ADB 연동 재발 방지 정책 |
| [guide_baron_sso_reference_source_2026-07-02.md](guide_baron_sso_reference_source_2026-07-02.md) | tdc114plus Baron SSO 참조 소스 기준 |
| [scenario_staging_baron_sso_login_verification_2026-07-06.md](scenario_staging_baron_sso_login_verification_2026-07-06.md) | staging Baron SSO 승인 로그인 검증 시나리오 |
| [00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md](00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md) | tdc114plus 분리형 API 전환 정책 |
| [00_policy_tdc114plus_auth_repo_2026-07-15.md](00_policy_tdc114plus_auth_repo_2026-07-15.md) | tdc114plus-auth 저장소 운영 정책 |
| [00_policy_tdc114plus_auth_operations_2026-07-15.md](00_policy_tdc114plus_auth_operations_2026-07-15.md) | tdc114plus-auth 운영/커밋 정책 |
| [00_guide_tdc114plus_auth_broker_redirect_flow_2026-07-15.md](00_guide_tdc114plus_auth_broker_redirect_flow_2026-07-15.md) | TDC114PLUS / tdc114plus-auth / Baron SSO Redirect Flow |
| [00_policy_tdc114plus_screen_feature_2026-07-07.md](00_policy_tdc114plus_screen_feature_2026-07-07.md) | tdc114plus 화면별/기능별 정책 |
| [00_guide_tdc114plus_external_api_usage_2026-07-03.md](00_guide_tdc114plus_external_api_usage_2026-07-03.md) | tdc114plus 외부 API 사용 및 앱 내 활용 정리 |
| [00_guide_tdc114plus_swagger_feature_mapping_2026-07-07.md](00_guide_tdc114plus_swagger_feature_mapping_2026-07-07.md) | tdc114plus Swagger API 목록 및 Feature 매핑 |
| [00_contract_tdc114plus_api_2026-07-02.md](00_contract_tdc114plus_api_2026-07-02.md) | tdc114plus API 계약 |
| [guide_tdc114plus_development_decision_brief_2026-07-01.md](guide_tdc114plus_development_decision_brief_2026-07-01.md) | tdc114plus(가칭) 신규 앱 개발 판단 문서 |
| [dev_env_tdc114plus_setup_plan_2026-07-02.md](dev_env_tdc114plus_setup_plan_2026-07-02.md) | tdc114plus 개발환경 구성 작업순서 |
| [review_tdc114plus_policy_document_2026-07-07.md](review_tdc114plus_policy_document_2026-07-07.md) | tdc114plus 정책 문서 개편 검토 |
| [00_policy_tdc114plus_development_2026-07-02.md](00_policy_tdc114plus_development_2026-07-02.md) | tdc114plus 개발 정책 |
| [guide_tdc114plus_script_automation_plan_2026-07-02.md](guide_tdc114plus_script_automation_plan_2026-07-02.md) | tdc114plus 테스트 자동화 스크립트 계획 |
| [00_policy_tdc114plus_testing_2026-07-02.md](00_policy_tdc114plus_testing_2026-07-02.md) | tdc114plus 테스트 정책 |
| [00_guide_tdc114plus_work_progress_timetable_2026-07-02.md](00_guide_tdc114plus_work_progress_timetable_2026-07-02.md) | tdc114plus 작업진행 절차 및 타임테이블 |
| [checklist_android_device_startup_2026-07-09.md](checklist_android_device_startup_2026-07-09.md) | 공기계 USB 테스트 시작 체크리스트 |
하위 디렉터리의 Markdown 파일은 이 목록에서 제외했습니다.
참고:
- Android Studio / WSL ADB 연동 상세 타임테이블은 `docs/troubleshooting/android-studio-wsl-adb-timetable-260703.md`를 참고한다.
- 반복 지연 대응 정리는 `docs/troubleshooting/flutter-docker-repeated-delay-countermeasures-2026-07-03.md`를 참고한다.