express-openapi-validator PR 여정기! HTTP 인증 로직 개선 하기 🚀

express-openapi-validator

 

안녕하세요! express-openapi-validator의 HTTP 인증 관련 이슈를 해결하기 위해 PR을 제출했던 과정을 공유드리려고 합니다.

이전 포스트에서 express-openapi-validator를 사용하면서 발견한 인증 관련 이슈를 다뤘었는데요, 간단히 요약드리면:

Express.js로 REST API를 구축하며 JWT를 http-only 쿠키로 전달하려 했는데,
Authorization 헤더와 CSRF 토큰 검증에서 문제가 발생했습니다.

특히 validateHttp() 메서드가 Authorization 헤더를 필수로 요구하는 바람에,
쿠키로 JWT를 전달하는 상황에서도 헤더가 필요한 상황이 됐죠.

코드를 분석해보니 SecuritySchemes와 AuthValidator 클래스의 validateHttp 메서드에서 이 로직을 처리하고 있었고,
type: http로 설정된 스킴에서 Authorization 헤더를 강제하고 있었습니다.

 

이 문제를 해결하기 위해 Pull Request를 제출했고, 여러 번의 코드 리뷰와 수정 과정을 거쳐 마침내 Merge가 되어 express-openapi-validator의 Contributor가 된 여정을 오늘 상세히 공유드리려고 합니다! 🎉

🎯 첫 번째 시도: 쿠키 지원 추가

처음에는 단순히 Authorization 헤더 외에도 쿠키를 통한 인증을 지원하도록 다음과 같이 코드를 수정했습니다:

if (!authHeader && !authCookie) {
  throw Error(`Authorization header or cookie required`);
}

if (type === 'bearer') {
  if (authHeader && !authHeader.includes('bearer')) {
    throw Error(`Authorization header with scheme 'Bearer' required`);
  }

  if (!authHeader && authCookie === undefined) {
    throw Error(`Bearer token required in authorization header or cookie`);
  }
}

💡 코드 리뷰 피드백

제가 제출한 PR에 대해 메인테이너께서 중요한 피드백을 주셨습니다:

1. OpenAPI 명세에 따르면, in: cookie로 지정된 경우와 그렇지 않은 경우를 구분해야 함
2. 에러 메시지도 각각의 상황에 맞게 다르게 처리되어야 함
   • 일반적인 경우: "Authorization header required"
   • 쿠키 인증의 경우: "Cookie authentication required"

🔨 두 번째 시도: 명세 기반 수정

피드백을 반영하여 코드를 수정했지만, 여기서 또 하나의 실수가 있었습니다. 바로 프로젝트의 기존 코드 스타일을 해치는 변경사항이 포함된 것이었죠..

 

예를 들어 함수 시그니처나 들여쓰기, 괄호 위치 등이 프로젝트의 기존 스타일과 달랐죠.

// 제가 수정한 코드
function extractErrorsFromResults(
  results: (SecurityHandlerResult | SecurityHandlerResult[])[],
) {
  return results
    .map((result) => {
      if (Array.isArray(result)) {
        return result.map((it) => it).filter((it) => !it.success);
      }
      return [result].filter((it) => !it.success);
    })
    .flatMap((it) => [...it]);
}

// 원래 프로젝트 스타일
function extractErrorsFromResults(results: (SecurityHandlerResult | SecurityHandlerResult[])[]) {
  return results.map(result => {
    if (Array.isArray(result)) {
      return result.map(it => it).filter(it => !it.success);
    }
    return [result].filter(it => !it.success);
  }).flatMap(it => [...it]);
}

 

이를 빠르게 원래 프로젝트의 스타일대로 되돌리고 커밋을 추가했습니다.

하지만 여기서 끝이 아니었죠. CI 파이프라인에서 테스트를 돌려보니 두 가지 심각한 문제가 발견되었습니다:

🐛 테스트 실패 발견

이후 CI에서 두 가지 테스트가 실패한다는 것을 발견했습니다:

1. Basic 인증에서 헤더가 없을 때 발생하는 에러
2. undefined.includes() 호출로 인한 에러

AssertionError: expected 'Cannot read properties of undefined (…' 
to equal 'Authorization header required'

 

결론은 authHeader가 undefined일 때 발생하는 에러 메시지 문제로 인한 테스트 실패였습니다.

✨ 최종 해결책

모든 피드백과 테스트 케이스를 고려하여 다음과 같이 코드를 최종 수정했습니다:

private validateHttp(): void {
  if (['http'].includes(scheme.type.toLowerCase())) {
    const authHeader = req.headers['authorization']?.toLowerCase();
    const authCookie = req.cookies[scheme.name] || req.signedCookies?.[scheme.name];

    const type = scheme.scheme?.toLowerCase();
    if (type === 'bearer') {
      if (authHeader && !authHeader.includes('bearer')) {
        throw Error(`Authorization header with scheme 'Bearer' required`);
      }
      
      if (!authHeader && !authCookie) {
        throw Error(scheme.in === 'cookie' 
          ? `Cookie authentication required`
          : `Authorization header required`);
      }
    }

    if (type === 'basic') {
      if (!authHeader) {
        throw Error(`Authorization header required`);
      }
      if (!authHeader.includes('basic')) {
        throw Error(`Authorization header with scheme 'Basic' required`);
      }
    }
  }
}

주요 개선사항:

1. Basic 인증과 Bearer 인증의 명확한 구분
2. 쿠키 기반 인증 지원 (OpenAPI 명세 준수)
3. 적절한 에러 메시지 처리
4. undefined 체크 강화

🎓 배운 점

1. OpenAPI 명세를 더 꼼꼼히 살펴봐야 했습니다
2. 프로젝트의 전체 테스트 실행의 중요성을 다시 한번 깨달았습니다
3. 코드 스타일 가이드를 준수하는 것의 중요성을 배웠습니다

이렇게 해서 express-openapi-validator에 작은 기여를 할 수 있었네요. 오픈소스 기여는 언제나 새로운 배움의 기회인 것 같습니다.

다음에는 또 어떤 재미있는 문제를 해결하게 될지 기대가 됩니다! 😊