create-entity-app-server 0.0.3

package/docs/flows.md

@@ -0,0 +1,581 @@
+# 기능별 흐름도
+
+---
+
+## 목차
+
+- [1. 로그인](#1-로그인)
+- [2. 회원가입](#2-회원가입)
+- [3. 회원 탈퇴](#3-회원-탈퇴)
+- [4. OAuth 소셜 로그인 (리다이렉트 · 콜백)](#4-oauth-소셜-로그인-리다이렉트--콜백)
+- [5. OAuth 계정 연동 관리](#5-oauth-계정-연동-관리)
+- [6. 2FA (TOTP)](#6-2fa-totp)
+- [7. 이메일 인증](#7-이메일-인증)
+- [8. 비밀번호 재설정](#8-비밀번호-재설정)
+- [9. 엔티티 CRUD (프록시)](#9-엔티티-crud-프록시)
+- [10. 파일 업로드 · 다운로드 (프록시)](#10-파일-업로드--다운로드-프록시)
+- [11. 엔티티 훅](#11-엔티티-훅)
+
+---
+
+## 1. 로그인
+
+> **담당**: Go 서버 (JWT 발급은 보안 프리미티브) · 앱서버는 프록시만
+
+```
+클라이언트
+    │
+    │  POST /api/v1/auth/login
+    │  { email, password }
+    ▼
+앱서버 (프록시)
+    │
+    │  프록시 → POST /v1/auth/login
+    ▼
+Go 서버
+    │
+    ├─ 이메일로 account 조회
+    ├─ bcrypt 비밀번호 검증
+    ├─ 계정 상태 확인 (active / dormant / withdrawn)
+    ├─ 휴면 계정 → 401 + dormant 코드
+    │
+    ├─ 2FA 활성화 여부 확인
+    │   ├─ 2FA 비활성화 → access_token + refresh_token 발급
+    │   └─ 2FA 활성화  → two_factor_token 발급 (단기)
+    │
+    └─ 응답 반환
+    │
+    ▼
+앱서버 (프록시 응답 그대로 전달)
+    │
+    ▼
+클라이언트
+    │
+    │  (2FA 활성화된 경우)
+    ▼
+    POST /api/v1/account/2fa/verify  [앱서버 담당]
+    → two_factor_token + TOTP 코드 검증 → JWT 발급
+```
+
+---
+
+## 2. 회원가입
+
+> **담당**: 앱서버 (가입 절차는 비즈니스 규칙)
+
+```
+클라이언트
+    │
+    │  POST /api/v1/account/register
+    │  { email, password, name, ... }
+    ▼
+앱서버 (routes/account/register/)
+    │
+    ├─ 입력값 검증 (이메일 형식, 비밀번호 정책)
+    ├─ 중복 이메일 확인 (entityServer.list)
+    │
+    ├─ 이메일 인증 필요 여부 확인 (email-verify config)
+    │   ├─ 인증 필요 → 계정 status=pending 으로 임시 생성
+    │   │              → email-verify/send 내부 호출 → 인증 메일 발송
+    │   │              → 201 반환
+    │   └─ 인증 불필요 → 계정 status=active 로 바로 생성
+    │                   → 환영 메일 발송 (설정에 따라)
+    │                   → 201 반환
+    │
+    └─ entityServer.submit("account", data)  ← Go CRUD API
+    │
+    ▼
+Go 서버 (엔티티 CRUD)
+    │
+    ├─ 비밀번호 bcrypt 해싱 (submit 훅 내부)
+    ├─ account 레코드 저장
+    └─ seq 반환
+    │
+    ▼
+앱서버
+    │
+    └─ sendEmail(환영/인증 메일)  ← Go SMTP API 또는 앱서버 직접 발송
+    │
+    ▼
+클라이언트 (201 Created)
+```
+
+---
+
+## 3. 회원 탈퇴
+
+> **담당**: 앱서버 (이메일 발송 판단) + Go 서버 (익명화 처리)
+
+```
+클라이언트
+    │
+    │  POST /api/v1/account/withdraw
+    │  Authorization: Bearer {access_token}
+    │  { passwd? }
+    ▼
+앱서버 (routes/account/withdraw/)
+    │
+    ├─ JWT에서 account_seq 추출
+    ├─ account 조회 (entityServer.get) → email 저장 (익명화 전 확보)
+    │
+    ├─ POST ${ENTITY_SERVER_URL}/v1/auth/withdraw  ← Go 내부 직접 호출
+    │     Authorization: Bearer {access_token} 그대로 전달
+    │     ↓
+    │   Go 서버 (HandleWithdraw)
+    │     ├─ 비밀번호 검증 (옵션)
+    │     ├─ 이메일 → withdrawn_XXXXXX@anonymized.local
+    │     ├─ name → "탈퇴회원"
+    │     ├─ account_oauth 레코드 비활성화
+    │     ├─ password_history 삭제
+    │     ├─ account status → withdrawn
+    │     └─ refresh_token 폐기
+    │
+    ├─ 탈퇴 완료 이메일 발송 (fire-and-forget)
+    │   sendEmail(미리 저장한 email, "withdraw-complete" 템플릿)
+    │
+    └─ 200 OK 반환
+    │
+    ▼
+클라이언트
+```
+
+---
+
+## 4. OAuth 소셜 로그인 (리다이렉트 · 콜백)
+
+> **담당**: 앱서버 (소셜 로그인 흐름은 비즈니스 규칙)
+> **지원 프로바이더**: Google · GitHub · Naver · Kakao · Line · Apple
+
+```
+[리다이렉트 단계]
+
+클라이언트
+    │
+    │  GET /api/v1/oauth/:provider
+    │  (예: /api/v1/oauth/google)
+    ▼
+앱서버 (routes/oauth/handlers/redirect.ts)
+    │
+    ├─ oauth.json에서 프로바이더 설정 로드
+    ├─ PKCE 지원 여부 확인 (Apple, Line)
+    │   └─ PKCE 필요 → code_verifier 생성 → code_challenge 계산
+    ├─ HMAC-SHA256 state 토큰 생성 (CSRF 방지)
+    │   format: base64url(provider:nonce).mac
+    ├─ state 인메모리 맵에 저장 (TTL: config state_ttl_sec)
+    └─ 302 Redirect → 프로바이더 인증 URL
+       (auth_url?client_id=...&state=...&code_challenge=...&scope=...)
+    │
+    ▼
+프로바이더 (Google / GitHub / Naver 등)
+    │
+    │  사용자 로그인 + 동의
+    ▼
+
+[콜백 단계]
+
+프로바이더
+    │
+    │  GET/POST /api/v1/oauth/:provider/callback
+    │  ?code=...&state=...
+    ▼
+앱서버 (routes/oauth/handlers/callback.ts)
+    │
+    ├─ state 검증 (HMAC-SHA256, TTL, provider 일치)
+    ├─ code → access_token 교환 (프로바이더 token_url 호출)
+    │   └─ Apple: ES256 JWT client_secret 자동 생성 후 교환
+    │   └─ PKCE: code_verifier 함께 전송
+    ├─ 사용자 정보 조회
+    │   ├─ Google : id_token 파싱 또는 userinfo endpoint
+    │   ├─ GitHub : /user + /user/emails
+    │   ├─ Naver  : response 객체에서 추출
+    │   ├─ Kakao  : kakao_account.email 도트 표기 추출
+    │   ├─ Apple  : id_token JWT payload + form user JSON
+    │   └─ Line   : profile API + id_token email
+    │
+    ├─ account upsert (upsert.ts)
+    │   ├─ Step 1: account_oauth(provider, provider_id) → account_seq 조회
+    │   ├─ Step 2: 없으면 email로 account 조회 → 자동 연동
+    │   └─ Step 3: 모두 없으면 신규 account + account_oauth 생성
+    │              (entityServer.submit → Go CRUD)
+    │
+    ├─ 2FA 활성화 여부 확인
+    │   ├─ 2FA 없음 → JWT (access_token + refresh_token) 발급
+    │   └─ 2FA 있음 → two_factor_token 발급
+    │
+    ├─ success_redirect_url 설정 여부
+    │   ├─ 있음 → 302 Redirect (token을 쿼리파라미터 또는 쿠키로 전달)
+    │   └─ 없음 → JSON 응답 { access_token, refresh_token }
+    │
+    ▼
+클라이언트
+```
+
+---
+
+## 5. OAuth 계정 연동 관리
+
+> **담당**: 앱서버 (연동 상태 관리는 비즈니스 규칙)
+
+### 연동 (Link)
+
+```
+클라이언트
+    │  POST /api/v1/account/oauth/link
+    │  Authorization: Bearer {access_token}
+    │  { provider, code, state?, redirect_uri? }
+    ▼
+앱서버 (routes/account/oauth/handlers/link.ts)
+    │
+    ├─ JWT에서 account_seq 추출
+    ├─ state 검증 (있는 경우)
+    ├─ code → access_token 교환
+    ├─ 사용자 정보 조회
+    ├─ 이미 연동된 provider 확인
+    │   ├─ active → 409 Conflict
+    │   └─ unlinked → 재활성화 (status=active, linked_at=now())
+    ├─ 다른 계정에 연동된 provider_id 확인 → 409
+    └─ 신규 account_oauth 레코드 생성
+    │
+    ▼
+클라이언트 (200 OK)
+```
+
+### 연동 해제 (Unlink)
+
+```
+클라이언트
+    │  DELETE /api/v1/account/oauth/link/:provider
+    │  Authorization: Bearer {access_token}
+    ▼
+앱서버 (routes/account/oauth/handlers/unlink.ts)
+    │
+    ├─ JWT에서 account_seq 추출
+    ├─ account_oauth 레코드 확인 (active)
+    ├─ 로그인 수단 보호: has_password=false + 다른 활성 연동 없음 → 400
+    └─ account_oauth status=unlinked, unlinked_at=now()
+    │
+    ▼
+클라이언트 (200 OK)
+```
+
+---
+
+## 6. 2FA (TOTP)
+
+> **담당**: 앱서버 (인증 절차는 비즈니스 규칙)
+
+### 설정 흐름
+
+```
+클라이언트
+    │  POST /api/v1/account/2fa/setup
+    │  Authorization: Bearer {access_token}
+    ▼
+앱서버 (routes/account/2fa/handlers/setup.ts)
+    │
+    ├─ JWT에서 account_seq 추출
+    ├─ TOTP 비밀키 생성 (base32)
+    ├─ QR코드 URL 생성 (otpauth://)
+    ├─ QR코드 이미지 생성
+    ├─ account.totp_secret_pending에 저장
+    ├─ setup_token 발급 (단기, 5분)
+    └─ { qr_code, secret, setup_token } 반환
+    │
+    ▼
+클라이언트 → OTP 앱으로 QR 스캔
+    │
+    │  POST /api/v1/account/2fa/setup/verify
+    │  { setup_token, code }
+    ▼
+앱서버 (routes/account/2fa/handlers/setup-verify.ts)
+    │
+    ├─ setup_token 검증
+    ├─ TOTP 코드 검증 (window: skew ±1)
+    ├─ totp_secret_pending → totp_secret 이동
+    ├─ totp_enabled = true
+    ├─ 리커버리 코드 10개 생성 + bcrypt 해싱 저장
+    └─ 리커버리 코드 반환 (1회만 표시)
+```
+
+### 로그인 2단계 검증 흐름
+
+```
+[로그인 → two_factor_token 발급]
+    │
+클라이언트
+    │  POST /api/v1/account/2fa/verify
+    │  { two_factor_token, code }
+    ▼
+앱서버 (routes/account/2fa/handlers/verify.ts)
+    │
+    ├─ two_factor_token 검증 (단기 토큰)
+    ├─ token에서 account_seq 추출
+    ├─ account.totp_secret 조회
+    ├─ TOTP 코드 검증 (replay 방지: 사용된 코드 캐싱)
+    └─ 검증 성공 → JWT (access_token + refresh_token) 발급
+    │
+    ▼
+클라이언트
+```
+
+---
+
+## 7. 이메일 인증
+
+> **담당**: 앱서버 (인증 절차는 비즈니스 규칙)
+
+```
+[코드 방식]
+
+클라이언트
+    │  POST /api/v1/email-verify/send
+    │  { email, method: "code" }
+    ▼
+앱서버 (routes/email-verify/handlers/send.ts)
+    │
+    ├─ 이메일로 account 조회
+    ├─ Rate Limit 확인 (최근 N분 이내 재발송 제한)
+    ├─ 6자리 숫자 코드 생성 + SHA256 해싱
+    ├─ email_verification 엔티티에 저장 (TTL + 시도횟수)
+    └─ SMTP 발송 (인증코드 템플릿)
+    │
+    ▼
+클라이언트
+    │  POST /api/v1/email-verify/confirm
+    │  { email, code }
+    ▼
+앱서버 (routes/email-verify/handlers/confirm.ts)
+    │
+    ├─ 코드 해시 비교
+    ├─ TTL 확인, 시도 횟수 확인 (최대 N회)
+    ├─ account.email_verified = true
+    ├─ account.status = active (pending → active)
+    └─ 검증 토큰 반환
+    │
+    ▼
+클라이언트 (검증 완료)
+
+[링크 방식]
+
+send → 랜덤 토큰 생성 → 링크 이메일 발송
+    │
+GET /api/v1/email-verify/activate?token=...
+    ▼
+앱서버 → 토큰 검증 → account 활성화 → Redirect
+```
+
+---
+
+## 8. 비밀번호 재설정
+
+> **담당**: 앱서버 (재설정 방식은 비즈니스 규칙)
+
+### 임시비밀번호 방식 (기본)
+
+```
+클라이언트
+    │  POST /api/v1/password-reset/request
+    │  { email }
+    ▼
+앱서버 (routes/password-reset/)
+    │
+    ├─ email로 account 조회 (없어도 200 반환 — 사용자 열거 방지)
+    ├─ 임시 비밀번호 생성 (랜덤 8~12자)
+    ├─ POST /api/v1/auth/change-password 내부 호출
+    │   → Go 서버에서 bcrypt 해싱 + 즉시 저장
+    └─ SMTP 발송 (임시 비밀번호 포함)
+    │
+    ▼
+클라이언트 (이메일 수신 → 임시 비밀번호로 로그인)
+    │
+    └─ 로그인 후 비밀번호 변경 권장
+```
+
+### 링크 방식
+
+```
+클라이언트
+    │  POST /api/v1/password-reset/request
+    │  { email }
+    ▼
+앱서버 (routes/password-reset/)
+    │
+    ├─ email로 account 조회 (없어도 200 반환 — 사용자 열거 방지)
+    ├─ 랜덤 리셋 토큰 생성 (32바이트 hex)
+    ├─ password_reset_token 엔티티에 저장 (TTL: 30분)
+    └─ SMTP 발송 (재설정 링크 포함)
+    │
+    ▼
+클라이언트 (이메일 수신 → 링크 클릭)
+    │
+    │  GET /api/v1/password-reset/validate?token=...
+    ▼
+앱서버
+    │
+    ├─ 토큰 유효성 확인 (TTL, 사용 여부)
+    └─ 200 OK (유효) 또는 400 (만료/사용됨)
+    │
+    ▼
+클라이언트 (새 비밀번호 입력)
+    │
+    │  POST /api/v1/password-reset/verify
+    │  { token, new_password }
+    ▼
+앱서버
+    │
+    ├─ 토큰 검증
+    ├─ 비밀번호 정책 검증
+    ├─ POST /api/v1/auth/change-password 내부 호출
+    │   → Go 서버에서 bcrypt 해싱 + 저장
+    ├─ 토큰 사용 처리 (재사용 방지)
+    └─ 200 OK
+    │
+    ▼
+클라이언트
+```
+
+### 관리자 리셋 방식
+
+```
+관리자 (admin 역할 계정)
+    │
+    │  POST /api/v1/admin/account/:seq/reset-password
+    │  Authorization: Bearer {admin_access_token}
+    ▼
+앱서버 (admin 라우트)
+    │
+    ├─ JWT decode → role 확인 (admin 권한 없으면 403)
+    ├─ account_seq로 account 조회 → email 확보
+    │   (익명화 전 이메일 미리 저장)
+    ├─ 임시 비밀번호 생성 (랜덤 8~12자)
+    ├─ 게이트웨이 account/change-password 핸들러에서 직접 처리
+    │   ├─ 현재 비밀번호 검증
+    │   ├─ bcrypt 해싱
+    │   └─ 비밀번호 저장 + 이력 기록
+    │
+    ├─ SMTP 발송 (임시 비밀번호 + 관리자 리셋 안내)
+    │   sendEmail(email, "admin-password-reset", { temp_password })
+    └─ 200 OK
+    │
+    ▼
+관리자 (처리 완료)
+사용자 (이메일 수신 → 임시 비밀번호로 로그인 → 비밀번호 변경 권장)
+```
+
+> **주의**: 임시 비밀번호는 응답 본문에 포함하지 않는다 — 이메일로만 전달한다.
+
+---
+
+## 9. 엔티티 CRUD (프록시)
+
+> **담당**: Go 서버 · 앱서버는 투명 프록시
+
+```
+클라이언트
+    │  POST /api/v1/entity/:entity/submit
+    │  Authorization: Bearer {access_token}
+    │  { ... 데이터 ... }
+    ▼
+앱서버 (system/proxy/register.ts)
+    │
+    ├─ JWT decode (user 정보 추출, verify는 Go에서)
+    ├─ 엔티티 훅 확인 (beforeSubmit 등록된 경우)
+    │   └─ beforeSubmit(entity, ctx, user) 실행
+    │       └─ 예외 throw 시 → 요청 차단 (4xx 반환)
+    │
+    │  프록시 → POST /v1/entity/:entity/submit
+    ▼
+Go 서버 (엔티티 CRUD)
+    │
+    ├─ JWT verify + RBAC 접근 제어
+    ├─ 엔티티 JSON 정의 기반 유효성 검증
+    ├─ 필드 암호화 (설정된 경우)
+    ├─ DB insert/update
+    ├─ 변경 이력 저장
+    └─ { ok, seq } 반환
+    │
+    ▼
+앱서버
+    │
+    ├─ 엔티티 훅 (afterSubmit 등록된 경우)
+    │   └─ afterSubmit(entity, ctx, user) 비동기 실행
+    │       (알림 발송, 외부 API 호출 등)
+    │
+    └─ 클라이언트에 응답 반환
+    │
+    ▼
+클라이언트
+```
+
+---
+
+## 10. 파일 업로드 · 다운로드 (프록시)
+
+> **담당**: Go 서버 · 앱서버는 투명 프록시
+
+```
+[업로드]
+
+클라이언트
+    │  POST /api/v1/files/:entity/upload
+    │  Authorization: Bearer {access_token}
+    │  multipart/form-data
+    ▼
+앱서버 (프록시, timeout: 60s)
+    │
+    │  → POST /v1/files/:entity/upload
+    ▼
+Go 서버
+    │
+    ├─ JWT verify + RBAC
+    ├─ 용량 쿼터 확인
+    ├─ 파일 저장 (로컬 / S3 등 설정에 따라)
+    ├─ files 엔티티에 메타 저장
+    └─ { uuid, url } 반환
+    │
+    ▼
+클라이언트
+
+[다운로드 — 인증 없이 접근 가능한 임시 URL]
+
+클라이언트
+    │  POST /api/v1/files/token/:uuid   ← 임시 토큰 발급
+    ▼
+Go 서버 → 단기 토큰 반환
+    │
+GET /v1/files/:uuid?token=...  ← 토큰으로 직접 접근 가능
+```
+
+---
+
+## 11. 엔티티 훅
+
+> **담당**: 앱서버 (`app/hooks/`)
+
+```
+[beforeSubmit 예시: 특정 엔티티 제출 전 데이터 변환]
+
+Go 서버 CRUD 요청 수신 전
+    │
+앱서버 훅 로더 (system/hooks/)
+    │
+    ├─ app/hooks/registry.ts에서 엔티티명 → EntityHook 매핑 조회
+    ├─ beforeSubmit(entity, { old, new }, user) 실행
+    │   ├─ 데이터 가공 / 검증 / 외부 API 확인
+    │   ├─ throw → 요청 차단 (4xx)
+    │   └─ return data → 변환된 데이터로 Go에 전달
+    │
+Go 서버에서 실제 저장
+
+[afterSubmit 예시: 저장 후 알림 발송]
+
+Go 서버 CRUD 완료
+    │
+앱서버 훅 (비동기)
+    │
+    └─ afterSubmit(entity, { old, new }, user)
+        ├─ 변경 내용에 따라 SMTP 발송 판단
+        ├─ sendEmail(...)  ← Go SMTP API 호출
+        ├─ 외부 CRM webhook 호출
+        └─ 예외 → 로그만 남김 (이미 저장 완료됨)
+```

package/docs/getting-started.md

@@ -0,0 +1,83 @@
+# 시작하기
+
+## 1. 설치
+
+```bash
+npm create entity-app-server@latest my-gateway
+cd my-gateway
+```
+
+설치 후 폴더 구조:
+
+```
+my-gateway/
+  system.js       — 서버 코어 번들 (수정 불가)
+  system-api.js   — 공개 API 번들
+  app/            — 비즈니스 로직 (TypeScript, 자유롭게 수정)
+  configs/        — JSON 설정 파일
+  entities/       — 엔티티 스키마
+  scripts/        — 운영 스크립트
+  .env            — 환경변수
+```
+
+---
+
+## 2. 환경변수 설정
+
+`.env` 파일을 열어 필수 값을 입력합니다:
+
+```env
+ENTITY_SERVER_URL=https://your-entity-server.com
+ENTITY_API_KEY=your-api-key
+ENTITY_HMAC_SECRET=your-hmac-secret
+JWT_SECRET=your-jwt-secret
+NODE_ENV=production
+```
+
+포트·호스트·로그 설정은 `configs/server.json`에서 합니다. → [설정 파일 가이드](configs.md)
+
+---
+
+## 3. 의존성 설치
+
+```bash
+npm install
+```
+
+---
+
+## 4. 실행
+
+```bash
+# 직접 실행
+node --import tsx/esm system.js
+
+# 또는 스크립트 사용
+./scripts/run.sh
+```
+
+서버가 `http://0.0.0.0:3000`에서 시작됩니다.
+
+헬스체크 확인:
+
+```bash
+curl http://localhost:3000/health
+```
+
+---
+
+## 5. 엔티티 스키마 동기화
+
+```bash
+./scripts/entity.sh
+```
+
+`entities/` 폴더의 JSON 스키마를 Entity Server에 등록합니다.
+
+---
+
+## 6. 다음 단계
+
+- [커스터마이징 가이드](README.md) — 라우트·훅·플러그인 추가 방법
+- [플러그인 설정](plugins/) — 결제·LLM·알림 설정 방법
+- [API 라우트](routes/) — 제공되는 API 엔드포인트 목록