데모 참고: 로그인 엔드포인트는 적응형 PoW(Proof of Work) 챌린지로 보호됩니다. 반복된 실패는 점점 더 높은 작업 증명 난이도를 요구합니다. 캐시 기반 속도 제한이 구현 및 테스트되었지만 현재 라이브 데모에서는 활성화되어 있지 않습니다. 활성화하려면 app.ts에서 createCacheClient를 활성화하세요.

Cloudflare Workers용으로 처음부터 구축한 인증 참조 구현입니다. PBKDF2 비밀번호 해싱, JWT 이중 토큰 세션, 상수 시간 비교, 슬라이딩 만료, 그리고 제거 가능한 관찰 가능성 플러그인을 포함하며, Hono, Turso(선택적 Valkey/Redis 캐싱 포함), 그리고 엄격한 TypeScript로 연결됩니다.

모든 설계 결정은 표준을 기반으로 합니다: 자격 증명에 NIST SP 800-63B, 키 유도에 NIST SP 800-132, 검증에 OWASP ASVS, JWT 모범 사례에 RFC 8725를 따릅니다.

제품을 출시하시나요? 대신 Better Auth 를 사용하세요. OAuth, 패스키, MFA, 속도 제한 등을 활성화된 플러그인 생태계와 함께 기본적으로 제공합니다. 이 저장소는 인증이 어떻게 작동하는지 가르쳐주기 위해 존재하며, 프로덕션 라이브러리를 대체하기 위한 것이 아닙니다.

이 저장소가 필요한 이유

• 문서뿐만 아니라 코드를 읽으세요 — 모든 보안 속성(타이밍 안전 거부, 세션 연결된 폐기, 알고리즘 고정)이 설명될 뿐만 아니라 구현되고 테스트되었습니다.
• NIST + OWASP + RFC 참조 전반에 걸쳐 — 각 결정 뒤에 있는 이유를 배울 수 있습니다.
• 630개 이상의 테스트 — 공격 벡터 스위트(토큰 변조, 알고리즘 혼동, 유니코드 경계 사례) 포함
• 관찰 가능성 플러그인 — 구조화된 감사 로깅, 적응형 PoW 챌린지, 에이전트 인증된 ops API, 그리고 WebSocket 이벤트 스트리밍 — Hono 미들웨어를 통해 연결되며, 핵심 인증을 수정하지 않고 설치/제거 가능
• 엣지용으로 구축됨 — Cloudflare Workers에서 Web Crypto API로 실행되며, Node.js 종속성 없음
• Apache-2.0 — 포크하여 가르치고, 배우고, 활용하세요

내부 내용

프로덕션 다음 단계

이 프로젝트는 교육적 범위를 벗어나는 기능을 의도적으로 생략합니다. 이 코드를 프로덕션으로 확장하거나(프로덕션 인증 시스템이 필요한지 평가하는 경우) 아래 표는 우선순위 계층별로 격차를 정리합니다.

대부분의 실제 프로젝트에서는 직접 구축하는 대신 Better Auth를 사용하세요.

중요 — 실제 사용자 전에 추가

높은 우선순위 — 프로덕션 신뢰

중간 우선순위 — 제품 확장 시

고급 — 엔터프라이즈 / 높은 보안

이 모든 것은 Better Auth를 사용하는 훌륭한 이유입니다.

저장소 구조

.
├── apps/
│   └── cloudflare-workers/    # 예제 Worker + Hono 라우트
├── packages/
│   ├── core/                  # 인증 서비스, 미들웨어, 암호화 유틸리티
│   ├── infrastructure/        # DB 클라이언트 + 유틸리티
│   ├── observability/         # 이벤트 발생, 적응형 챌린지, ops API (제거 가능 플러그인)
│   ├── schemas/               # Zod 스키마
│   └── types/                 # 공유 TypeScript 타입
├── tools/
│   └── cli/                   # plctl — /ops 표면용 Go TUI
└── docs/
    ├── adr/                   # 아키텍처 결정 기록
    └── audits/                # 보안 감사

시작하기

git clone https://github.com/vhscom/private-landing.git
cd private-landing
bun install
bun run dev

끝입니다. 계정, API 키, .env 파일이 필요 없습니다. 개발 서버는 로컬 SQLite 데이터베이스와 생성된 비밀로 시작됩니다. http://localhost:8788을 열어 계정을 등록하고 인증 흐름을 탐색하세요.

Turso 계정이 있나요? apps/cloudflare-workers/에 .dev.vars 파일을 넣고(.dev.vars.example 참조) bun run dev를 실행하면 자동으로 원격 데이터베이스와 함께 wrangler를 사용합니다. 로컬 서버를 강제로 사용하려면 bun run dev:local을 사용하세요.

테스트 및 배포 지침은 CONTRIBUTING.md를 참조하세요.

AI와 함께 사용하기

이 저장소에는 AI 어시스턴트를 위한 컨텍스트를 제공하는 CLAUDE.md 파일이 포함되어 있습니다. Claude Code, Cursor 또는 유사한 AI 기반 개발 도구를 사용할 때:

1. AI는 프로젝트 컨텍스트를 위해 자동으로 CLAUDE.md를 읽습니다.
2. docs/adr/의 아키텍처 결정 기록은 설계 선택을 설명합니다.
3. docs/audits/의 보안 감사는 보안 상태를 문서화합니다.
4. 테스트는 예상 동작과 경계 사례를 보여줍니다.

코드베이스는 명확한 모듈 경계, 포괄적인 타입, 설명적인 명명 규칙을 통해 AI가 읽을 수 있도록 설계되었습니다.

라이선스

Apache-2.0