Email Webhook Server

Cloudflare Email Worker와 연동하여 이메일을 수신하는 웹훅 서버입니다.

주요 기능

• [완료] Cloudflare Email Worker 완벽 지원
• [완료] 인증 미들웨어 (X-Webhook-Secret)
• [완료] 중복 이메일 자동 감지 및 방지
• [완료] JSON 파일로 이메일 영구 저장
• [완료] Path Traversal 보안 취약점 방지
• [완료] Docker 컨테이너 지원
• [완료] Winston 로깅 시스템
• [완료] Health check 엔드포인트

빠른 시작

1. 환경변수 설정

.env 파일의 WEBHOOK_SECRET을 변경하세요:

WEBHOOK_SECRET=your-strong-secret-key-here

2. Docker로 실행

docker compose up -d

서버가 http://localhost:30100에서 실행됩니다.

3. Cloudflare Email Worker 설정

workers.js 파일을 참고하여 Cloudflare Workers에 배포하세요.

환경변수 설정:

• WEBHOOK_URL: http://your-server:30100/webhook
• WEBHOOK_SECRET: .env 파일의 값과 동일하게 설정

API 엔드포인트

Health Check

GET /health

이메일 수신 (Cloudflare Email Worker용)

POST /webhook
Headers:
  Content-Type: application/json
  X-Webhook-Secret: your-webhook-secret

Body:
{
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "subject": "Email Subject",
  "messageId": "message-id-123",
  "body": "Email body content...",
  "headers": {...},
  "bodyPreview": "Preview text..."
}

이메일 목록 조회

GET /webhook/list
Headers:
  X-Webhook-Secret: your-webhook-secret

특정 이메일 조회

GET /webhook/:filename
Headers:
  X-Webhook-Secret: your-webhook-secret

디렉토리 구조

.
├── src/
│   ├── server.js              # 메인 서버
│   ├── routes/
│   │   └── webhook.js         # 웹훅 라우트
│   ├── middlewares/
│   │   └── auth.js            # 인증 미들웨어
│   └── utils/
│       └── logger.js          # 로깅 유틸
├── data/                      # 이메일 저장 디렉토리
├── logs/                      # 로그 파일 디렉토리
├── Dockerfile
├── compose.yml
└── .env

개발 모드

npm install
npm run dev

보안 기능

1. 인증: X-Webhook-Secret 헤더로 요청 검증
2. Path Traversal 방지: 파일명 검증 및 basename 사용
3. 중복 방지: messageId 기반 중복 이메일 감지
4. Docker 보안: non-root user, dumb-init 사용

로그

• logs/combined.log: 모든 로그
• logs/error.log: 에러 로그만
• 콘솔: 실시간 컬러 로그

환경변수

변수	기본값	설명
PORT	3000	서버 포트
NODE_ENV	production	실행 환경
WEBHOOK_SECRET	-	웹훅 인증 시크릿 (필수)
LOG_LEVEL	info	로그 레벨
DATA_DIR	/app/data	이메일 저장 경로
LOGS_DIR	/app/logs	로그 파일 경로

Cloudflare KV를 사용한 중복 방지

Cloudflare Email Worker에서 KV를 사용하면 이중으로 중복을 방지할 수 있습니다:

1. Cloudflare Worker에서 KV로 1차 필터링
2. Webhook 서버에서 파일명으로 2차 필터링

# KV Namespace 생성
wrangler kv:namespace create "WEBHOOK_CACHE"

# wrangler.toml에 추가
[[kv_namespaces]]
binding = "WEBHOOK_CACHE"
id = "your-kv-namespace-id"

라이센스

MIT