From 57caca8dc8392d293ea2e9c27588d959f655bf13 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 15 Jul 2026 10:58:31 +0900 Subject: [PATCH] docs(auth): document official auth repo policy --- ...y_tdc114plus_auth_operations_2026-07-15.md | 202 ++++++++++++++++++ ..._policy_tdc114plus_auth_repo_2026-07-15.md | 193 +++++++++++++++++ docs/README.md | 46 ++++ 3 files changed, 441 insertions(+) create mode 100644 docs/00_policy_tdc114plus_auth_operations_2026-07-15.md create mode 100644 docs/00_policy_tdc114plus_auth_repo_2026-07-15.md create mode 100644 docs/README.md diff --git a/docs/00_policy_tdc114plus_auth_operations_2026-07-15.md b/docs/00_policy_tdc114plus_auth_operations_2026-07-15.md new file mode 100644 index 0000000..021cf40 --- /dev/null +++ b/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/`: 기능 추가 +- `fix/`: 버그 수정 +- `ops/`: 운영 설정, 실행 절차, 문서, 환경 가이드 +- `docs/`: 정책/가이드 문서 정리 + +예시: + +- `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 관련 서버 변경은 이 정책을 기준으로 저장소 분리, 커밋 분리, 검증 기록 분리를 유지한다. diff --git a/docs/00_policy_tdc114plus_auth_repo_2026-07-15.md b/docs/00_policy_tdc114plus_auth_repo_2026-07-15.md new file mode 100644 index 0000000..87e6038 --- /dev/null +++ b/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: ` 기록 +- auth 저장소 커밋 본문에 `Related-App-Commit: ` 기록 + +## 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` 저장소에서 관리한다. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..0475224 --- /dev/null +++ b/docs/README.md @@ -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`를 참고한다.