baron-sso/docs/client-log-policy.md

Client Log Policy

1. 목적

• 운영 환경에서 클라이언트 로그를 최소권한으로 수집하고, 민감정보 유출을 방지합니다.
• 장애 분석이 필요한 경우에만 명시적 디버그 옵션으로 로그 레벨을 확장합니다.

2. 환경별 수집 정책

2.1 기준 변수

• APP_ENV
• CLIENT_LOG_DEBUG
• (UserFront fallback) USERFRONT_DEBUG_LOG

2.2 동작 매트릭스

• APP_ENV != production|prod
  • 클라이언트 로그: DEBUG/INFO/WARN/ERROR 수집 허용
• APP_ENV == production|prod AND CLIENT_LOG_DEBUG 미설정
  • 클라이언트 로그: WARN/ERROR만 수집
  • INFO 네비게이션 노이즈 로그는 필터
• APP_ENV == production|prod AND CLIENT_LOG_DEBUG=true|1|on|yes
  • 클라이언트 로그: DEBUG/INFO/WARN/ERROR 수집 허용

3. 민감정보 마스킹 규칙

3.1 Key 기반 마스킹

아래 키는 값 전체를 *****로 치환합니다.

• password, currentPassword, newPassword, oldPassword
• token, accessToken, refreshToken
• secret, clientSecret
• authorization, cookie, setCookie
• verificationCode, code
• loginChallenge, loginVerifier
• sessionJwt, accessJwt, refreshJwt

3.2 문자열 패턴 마스킹

메시지 본문에서도 아래 패턴을 마스킹합니다.

• token=...
• authorization:... 또는 authorization=...
• JSON 문자열 내 민감 key/value

4. 구현 위치

• Backend
  • 정책/마스킹 로직: backend/internal/logger/client_log_policy.go
  • 수집 엔드포인트 적용: backend/cmd/server/main.go (POST /api/v1/client-log)
• UserFront
  • 정책/마스킹 로직: userfront/lib/core/services/log_policy.dart
  • 로그 출력/전송 정책: userfront/lib/core/services/logger_service.dart
  • 전송 직전 마스킹: userfront/lib/core/services/auth_proxy_service.dart

5. 검증

5.1 Backend

cd backend
go test ./internal/logger -count=1
go test ./cmd/server -count=1

5.2 UserFront

cd userfront
flutter test test/log_policy_test.dart

6. 운영 가이드

• 운영에서 디버그 로그가 필요하면 CLIENT_LOG_DEBUG=true를 명시적으로 설정하고, 이슈 해결 후 즉시 원복합니다.
• 운영에서도 민감정보 마스킹은 항상 강제되며 비활성화할 수 없습니다.