kevin/tdc114plus

Fork 0

Files

T

Codex 57caca8dc8 docs(auth): document official auth repo policy

2026-07-15 10:58:31 +09:00

5.1 KiB

Raw Blame History

tdc114plus-auth 운영/커밋 정책

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

목적: tdc114plus-auth 공식 저장소의 운영 기준, 커밋 경계, 검증 기준, tdc114plus 앱 저장소와의 교차 작업 규칙을 고정한다.

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. 커밋 경계 정책

한 커밋에는 아래 중 한 가지 성격만 담는다.

인증 기능 변경
세션/보안 로직 변경
proxy/API 동작 변경
테스트 추가/수정
운영 문서/실행 스크립트 변경

권장 원칙:

기능 변경과 포맷 변경을 섞지 않는다.
리팩터링과 동작 변경을 가능하면 분리한다.
문서 개정만 있을 때는 문서 커밋으로 따로 남긴다.
.env.example 변경은 실제 코드 변경과 강하게 연결될 때만 함께 커밋한다.

5. 커밋 메시지 규칙

권장 형식:

type(scope): summary

예시:

feat(auth): add Baron link poll completion handling

fix(callback): validate state before token exchange

feat(proxy): add org-context bearer session guard

docs(ops): update staging auth server startup guide

6. 앱 저장소와의 교차 작업 규칙

앱 저장소와 auth 저장소를 함께 바꿔야 하는 경우에도 한 저장소에서 한 커밋만 만든다.

원칙:

tdc114plus 앱 코드는 앱 저장소에서만 커밋한다.
tdc114plus-auth 서버 코드는 auth 저장소에서만 커밋한다.
서로 연관된 변경이면 커밋 본문에 상대 저장소 커밋 해시를 남긴다.

예시:

Related-App-Commit: abc1234

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 또는 관련 운영 문서 최신화 여부 확인

권장 검증 예:

go test ./...

go run ./cmd/server

실제 Baron 연동 변경이면 아래 중 최소 하나를 남긴다.

수동 검증 기록
로그 요약
관련 문서 링크

9. 운영 문서 정책

아래 내용이 바뀌면 문서를 함께 갱신한다.

callback URL
JWKS URI
base URL
proxy endpoint
env 변수 이름/역할
mock/baron 모드 동작 차이
앱이 의존하는 응답 필드

문서 우선순위:

auth 저장소 README.md
auth 저장소 docs/
앱 저장소의 auth 연동 문서

10. 배포/운영 해석

main은 배포 후보 기준으로 유지한다.
실험적 Baron 계약 검증은 feature 브랜치에서 먼저 진행한다.
운영 반영 전에는 개발용 IP 기반 URL보다 도메인 기반 URL을 우선 문서화한다.
114-auth.hmac.kr에서 114.hmac.kr로 통합 논의가 생기면, 먼저 auth 저장소 문서를 갱신하고 이후 앱 저장소 설정을 맞춘다.

11. 현재 기준 결론

tdc114plus-auth는 이미 공식 저장소가 존재하므로 생성 검토 단계는 종료됐다.
이제 필요한 것은 저장소 추가가 아니라 운영/커밋 규칙의 고정이다.
이후 auth 관련 서버 변경은 이 정책을 기준으로 저장소 분리, 커밋 분리, 검증 기록 분리를 유지한다.

5.1 KiB Raw Blame History