Cloudflare가 Claude와 함께 OAuth를 빌드하고 모든 프롬프트를 공개함

1 day ago 4

Cloudflare가 OAuth 2.1 프로바이더 프레임워크를 Cloudflare Workers용 TypeScript 라이브러리로 발표함
대부분의 구현은 Anthropic의 Claude LLM을 이용해 작성되고, Cloudflare 보안 엔지니어가 꼼꼼하게 검토함
이 라이브러리는 API 엔드포인트를 위한 인증 자동화와 토큰 관리 자동 처리를 제공
최신 OAuth 표준과 PKCE, 동적 클라이언트 등록, 접근 범위 설정 등 주요 기능을 지원
중요한 구간마다 엔드 투 엔드 암호화와 싱글-유스 리프레시 토큰 등 보안 설계를 강조

Cloudflare Workers를 위한 OAuth 2.1 프로바이더 프레임워크의 소개 및 중요성

이 오픈소스 프로젝트는 Cloudflare Workers 환경에서 쉽게 OAuth 2.1 인증 서버를 구현할 수 있도록 설계된 TypeScript 라이브러리임.
동종 타 프로젝트와 비교시, Cloudflare 플랫폼에 특화된 확장성과 원활한 통합, 그리고 보안 중심의 설계에서 강점이 큼
알고리듬, 프로토콜 표준 준수(RFC-8414, RFC-7591 등), 라이브러리 구조의 명확성 등에 중점이 맞춰져 있음
특히, 토큰 및 주요 시크릿 값의 해시화 저장, props의 엔드 투 엔드 암호화 등 안전성을 위해 세부적으로 설계됨
참고로, 라이브러리 코어 코드와 문서 대부분이 Claude LLM의 협력으로 작성되어 흥미로운 개발사례를 보여줌

주요 기능 및 장점

OAuthProvider로 Worker 코드를 래핑하여 API 엔드포인트에 대한 인증 기능 자동 부여
토큰 관리(생성, 저장, 검증, 폐기 등)가 자동 처리되어 직접 구현이 필요하지 않음
사용자는 fetch 핸들러 안에서 이미 인증된 사용자 정보를 바로 파라미터로 받아 활용 가능함
사용자 관리 및 인증, UI 구현 방식에 대한 제한 없음 (개발자가 원하는 구조와 프레임워크 자유롭게 선택 가능)
라이브러리의 저장소에는 오직 해시 정보만 저장되고, 비밀키 등 시크릿 자체는 저장되지 않음

사용 방법 핵심

OAuthProvider 인스턴스를 Worker 엔트리포인트로 내보내서 fetch 핸들러 역할을 수행할 수 있음
apiRoute, apiHandler 옵션으로 인증이 필요한 API 엔드포인트 구간과 실제 핸들러를 각각 지정함
authorizeEndpoint, tokenEndpoint, clientRegistrationEndpoint 등 각 표준 OAuth 엔드포인트 경로를 정의 가능함
필요한 경우 scope나 public client registration 등 정책 세분화 가능함
defaultHandler를 통해 API 외 요청 및 인증 실패 요청도 유연하게 처리 가능함

헬퍼 객체 및 API

env.OAUTH_PROVIDER를 fetch 핸들러에서 사용하여, OAuth 관련 요청 파싱, 클라이언트 정보 조회, 승인 완료 등에 활용 가능함
API 요청처리에서, access token이 유효한 경우 권한이 부여된 상태의 사용자별 props 정보를 ctx.props로 바로 접근 가능함
클라이언트 등록, 권한(authorization grant) 리스트, 특정 사용자에 대한 grant 열람 및 폐기 등도 공식 API로 제공함

Token Exchange Callback

토큰 발급·갱신 시, props 값을 동적으로 업데이트할 수 있는 콜백(tokenExchangeCallback) 지원
OAuth 클라이언트와 연동된 추가 토큰 교환(upstream token exchange) 등 복합 시나리오 지원 가능함
콜백에서 accessTokenProps, newProps, accessTokenTTL 등을 반환하여 맞춤형 동작 구현 가능함
accessTokenTTL 커스터마이징을 통해, 상위 OAuth 시스템과 토큰 만료 타이밍을 맞출 수 있음
props에는 민감 정보가 담길 수 있어 이 값 전체가 엔드 투 엔드로 암호화되어 저장됨

커스텀 에러 응답

onError 옵션을 사용해 에러 발생 시 Notfication 전송, 커스텀 로깅 등 대외 조치 가능함
반환 Response를 직접 정의하면, OAuthProvider가 유저에게 제공하는 에러 응답을 원하는 형태로 오버라이드 가능함

보안 관련 상세 설계

엔드 투 엔드 암호화

토큰 관련 데이터 및 시크릿은 해시로만 저장되고, grant props 정보는 토큰 자체로 암호화 저장하여 유출 사고 대응력을 높임
userId, metadata 등은 감사(audit) 및 폐기 용도 기록을 위해 암호화하지 않으며, 필요시 개발자가 추가 암호화 적용 가능함

싱글-유스 리프레시 토큰 설계

OAuth 2.1 요구대로 "클라이언트 바인딩 or 싱글 유스" 조건 중, 이 라이브러리는 최대 2개 병렬 리프레시 토큰 허용이라는 절충 설계 사용
이를 통해 네트워크 장애 등으로 새 토큰 저장이 실패해도 이전 토큰을 한 번 더 사용할 수 있는 안전장치 제공함

Claude 기반 개발 과정

본 라이브러리와 문서 다수는 Anthropic Claude LLM을 활용해 초안이 만들어졌으며, Cloudflare 엔지니어가 RFC 및 보안 기준에 맞춰 꼼꼼하게 리뷰함
초기에는 AI 코드 생성에 회의적이었으나, 실제 품질과 생산성 향상 경험을 통해 시각이 변화하였음
개발 흐름과 Claude의 프롬프트, 코드 개선 과정을 깃 커밋 히스토리에서 모두 투명하게 공개함