create-entity-app-server 0.0.3

package/src/app/routes/email-verify/handlers/activate.ts

@@ -0,0 +1,103 @@
+/**
+ * GET /activate — 링크 클릭 인증
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, entityServer, logger } from "@gateway/api";
+import type {
+    EmailVerifyConfig,
+    VerificationActivateQuery,
+} from "../types/index.ts";
+import { verifyCode } from "../verification-utils.ts";
+import { findAccountByEmail } from "./utils.ts";
+import { loadRegisterConfig } from "../../account/register/config-loader.ts";
+import { sendWelcomeEmail } from "../../account/register/handlers.ts";
+
+export function createActivateHandler(cfg: EmailVerifyConfig) {
+    return async function handleActivate(
+        req: FastifyRequest<{ Querystring: VerificationActivateQuery }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const email = ((req.query as VerificationActivateQuery).email ?? "")
+            .trim()
+            .toLowerCase();
+        const token = (
+            (req.query as VerificationActivateQuery).token ?? ""
+        ).trim();
+        const redirect = (req.query as VerificationActivateQuery).redirect;
+
+        if (!email || !token) {
+            reply.code(400).send(fail("email과 token은 필수입니다."));
+            return;
+        }
+
+        const account = await findAccountByEmail(email);
+        if (!account || !account.seq || !account.email_verify_code) {
+            reply.code(400).send(fail("유효하지 않은 인증 링크입니다."));
+            return;
+        }
+
+        if (account.email_verified) {
+            if (redirect === "1" && cfg.link_base_url) {
+                reply.redirect(`${cfg.link_base_url}?verified=1`);
+                return;
+            }
+            reply.send(ok({ message: "이미 인증된 이메일입니다." }));
+            return;
+        }
+
+        // 만료 확인
+        if (
+            !account.email_verify_expires_time ||
+            new Date(account.email_verify_expires_time).getTime() <= Date.now()
+        ) {
+            reply.code(401).send(fail("인증 링크가 만료되었습니다."));
+            return;
+        }
+
+        // 시도 횟수 확인 (링크 무차별 대입 방지)
+        const attempts = Number(account.email_verify_attempts ?? 0);
+        if (attempts >= cfg.max_attempts) {
+            reply.code(429).send(fail("최대 시도 횟수를 초과했습니다."));
+            return;
+        }
+
+        // 토큰 검증
+        if (!verifyCode(token, account.email_verify_code)) {
+            await entityServer.submit("account", {
+                seq: account.seq,
+                email_verify_attempts: attempts + 1,
+            } as Record<string, unknown>);
+            reply.code(401).send(fail("유효하지 않은 인증 링크입니다."));
+            return;
+        }
+
+        // 인증 성공
+        await entityServer.submit("account", {
+            seq: account.seq,
+            email_verified: true,
+            email_verify_code: null,
+            email_verify_expires_time: null,
+            email_verify_attempts: null,
+        } as Record<string, unknown>);
+
+        logger.info(
+            { accountSeq: account.seq, email },
+            "Email verified via link",
+        );
+
+        // 인증 완료 → 환영 메일 (register config의 send_welcome_email이 true인 경우)
+        const registerCfg = loadRegisterConfig();
+        if (registerCfg.send_welcome_email) {
+            sendWelcomeEmail(registerCfg, email).catch((err) =>
+                logger.error({ err, email }, "Activate: welcome email failed"),
+            );
+        }
+
+        if (redirect === "1" && cfg.link_base_url) {
+            reply.redirect(`${cfg.link_base_url}?verified=1`);
+            return;
+        }
+        reply.send(ok({ message: "이메일 인증이 완료되었습니다." }));
+    };
+}

package/src/app/routes/email-verify/handlers/change.ts

@@ -0,0 +1,106 @@
+/**
+ * POST /change — 이메일 변경 + 재인증 (JWT 필요)
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, entityServer, logger } from "@gateway/api";
+import type { EmailVerifyConfig, EmailChangeBody } from "../types/index.ts";
+import { verifyPassword } from "../../password-reset/password-utils.ts";
+import {
+    MAX_EMAIL_LEN,
+    isRateLimited,
+    getAccountSeqFromJwt,
+    getAccountBySeq,
+    findAccountByEmail,
+} from "./utils.ts";
+import { sendVerification } from "./send.ts";
+
+export function createChangeHandler(cfg: EmailVerifyConfig) {
+    return async function handleChange(
+        req: FastifyRequest<{ Body: EmailChangeBody }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const accountSeq = getAccountSeqFromJwt(req);
+        if (!accountSeq) {
+            reply.code(401).send(fail("인증이 필요합니다."));
+            return;
+        }
+
+        const newEmail = (req.body?.new_email ?? "").trim().toLowerCase();
+        if (!newEmail) {
+            reply.code(400).send(fail("new_email은 필수입니다."));
+            return;
+        }
+        if (newEmail.length > MAX_EMAIL_LEN) {
+            reply.code(400).send(fail("new_email is too long"));
+            return;
+        }
+
+        const account = await getAccountBySeq(accountSeq);
+        if (!account) {
+            reply.code(404).send(fail("계정을 찾을 수 없습니다."));
+            return;
+        }
+
+        // 비밀번호 확인 (OAuth 전용 계정이 아닌 경우)
+        if (account.passwd) {
+            const currentPwd = req.body?.current_password ?? "";
+            if (!currentPwd) {
+                reply.code(400).send(fail("현재 비밀번호가 필요합니다."));
+                return;
+            }
+            if (!verifyPassword(currentPwd, account.passwd)) {
+                reply.code(401).send(fail("비밀번호가 일치하지 않습니다."));
+                return;
+            }
+        }
+
+        // 동일 이메일 체크
+        if (newEmail === String(account.email ?? "").toLowerCase()) {
+            reply.code(400).send(fail("현재와 동일한 이메일입니다."));
+            return;
+        }
+
+        // 중복 이메일 체크
+        const existing = await findAccountByEmail(newEmail);
+        if (existing) {
+            reply.code(409).send(fail("이미 사용 중인 이메일입니다."));
+            return;
+        }
+
+        // Rate limit
+        if (isRateLimited(newEmail, cfg.rate_limit.per_email_per_hour)) {
+            reply.code(429).send(fail("발송 제한 횟수를 초과했습니다."));
+            return;
+        }
+
+        // 이메일 변경 + 인증 필드 초기화
+        await entityServer.submit("account", {
+            seq: accountSeq,
+            email: newEmail,
+            email_verified: false,
+            email_verify_code: null,
+            email_verify_expires_time: null,
+            email_verify_attempts: 0,
+        } as Record<string, unknown>);
+
+        // 새 이메일로 인증 코드 발송
+        try {
+            await sendVerification(cfg, accountSeq, newEmail, "code");
+        } catch (err) {
+            logger.error(
+                { err, email: newEmail },
+                "Email change: verification send failed",
+            );
+        }
+
+        reply.send(
+            ok({
+                message:
+                    "이메일이 변경되었습니다. 새 이메일로 인증 코드를 발송했습니다.",
+                email: newEmail,
+                email_verified: false,
+            }),
+        );
+    };
+}

package/src/app/routes/email-verify/handlers/confirm.ts

@@ -0,0 +1,87 @@
+/**
+ * POST /confirm — 인증 코드 검증
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, entityServer, logger } from "@gateway/api";
+import type {
+    EmailVerifyConfig,
+    VerificationConfirmBody,
+} from "../types/index.ts";
+import { verifyCode } from "../verification-utils.ts";
+import { findAccountByEmail } from "./utils.ts";
+import { loadRegisterConfig } from "../../account/register/config-loader.ts";
+import { sendWelcomeEmail } from "../../account/register/handlers.ts";
+
+export function createConfirmHandler(cfg: EmailVerifyConfig) {
+    return async function handleConfirm(
+        req: FastifyRequest<{ Body: VerificationConfirmBody }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const email = (req.body?.email ?? "").trim().toLowerCase();
+        const code = (req.body?.code ?? "").trim();
+
+        if (!email || !code) {
+            reply.code(400).send(fail("email과 code는 필수입니다."));
+            return;
+        }
+
+        const account = await findAccountByEmail(email);
+        if (!account || !account.seq || !account.email_verify_code) {
+            reply.code(400).send(fail("인증 요청이 없습니다."));
+            return;
+        }
+
+        if (account.email_verified) {
+            reply.send(ok({ message: "이미 인증된 이메일입니다." }));
+            return;
+        }
+
+        // 만료 확인
+        if (
+            !account.email_verify_expires_time ||
+            new Date(account.email_verify_expires_time).getTime() <= Date.now()
+        ) {
+            reply.code(401).send(fail("인증 코드가 만료되었습니다."));
+            return;
+        }
+
+        // 시도 횟수 초과
+        const attempts = Number(account.email_verify_attempts ?? 0);
+        if (attempts >= cfg.max_attempts) {
+            reply.code(429).send(fail("최대 시도 횟수를 초과했습니다."));
+            return;
+        }
+
+        // 코드 검증
+        if (!verifyCode(code, account.email_verify_code)) {
+            await entityServer.submit("account", {
+                seq: account.seq,
+                email_verify_attempts: attempts + 1,
+            } as Record<string, unknown>);
+            reply.code(401).send(fail("인증 코드가 일치하지 않습니다."));
+            return;
+        }
+
+        // 인증 성공
+        await entityServer.submit("account", {
+            seq: account.seq,
+            email_verified: true,
+            email_verify_code: null,
+            email_verify_expires_time: null,
+            email_verify_attempts: null,
+        } as Record<string, unknown>);
+
+        logger.info({ accountSeq: account.seq, email }, "Email verified");
+
+        // 인증 완료 → 환영 메일 (register config의 send_welcome_email이 true인 경우)
+        const registerCfg = loadRegisterConfig();
+        if (registerCfg.send_welcome_email) {
+            sendWelcomeEmail(registerCfg, email).catch((err) =>
+                logger.error({ err, email }, "Confirm: welcome email failed"),
+            );
+        }
+
+        reply.send(ok({ message: "이메일 인증이 완료되었습니다." }));
+    };
+}

package/src/app/routes/email-verify/handlers/index.ts

@@ -0,0 +1,20 @@
+/**
+ * email-verify handlers 진입점
+ *
+ * 기능별로 분리된 핸들러를 한 곳에서 re-export.
+ *
+ *   handlers/
+ *     utils.ts      — rate limit, JWT 파싱, account 조회 헬퍼
+ *     send.ts       — POST /send  +  sendVerification (외부 재사용 가능)
+ *     confirm.ts    — POST /confirm
+ *     activate.ts   — GET  /activate
+ *     status.ts     — GET  /status
+ *     change.ts     — POST /change
+ *     index.ts      — (이 파일) 일괄 re-export
+ */
+
+export { createSendHandler, sendVerification } from "./send.ts";
+export { createConfirmHandler } from "./confirm.ts";
+export { createActivateHandler } from "./activate.ts";
+export { createStatusHandler } from "./status.ts";
+export { createChangeHandler } from "./change.ts";

package/src/app/routes/email-verify/handlers/send.ts

@@ -0,0 +1,157 @@
+/**
+ * POST /send — 인증 코드/링크 발송
+ * sendVerification — 내부 발송 로직 (register 등 외부에서도 재사용 가능)
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, entityServer, logger, sendEmail } from "@gateway/api";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, "..", "templates");
+import type {
+    EmailVerifyConfig,
+    VerificationSendBody,
+} from "../types/index.ts";
+import {
+    generateNumericCode,
+    generateRandomToken,
+    hashVerificationValue,
+} from "../verification-utils.ts";
+import { MAX_EMAIL_LEN, isRateLimited, findAccountByEmail } from "./utils.ts";
+
+export function createSendHandler(cfg: EmailVerifyConfig) {
+    return async function handleSend(
+        req: FastifyRequest<{ Body: VerificationSendBody }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const email = (req.body?.email ?? "").trim().toLowerCase();
+        if (!email) {
+            reply.code(400).send(fail("email is required"));
+            return;
+        }
+        if (email.length > MAX_EMAIL_LEN) {
+            reply.code(400).send(fail("email is too long"));
+            return;
+        }
+
+        const method = req.body?.method ?? "code";
+        if (method !== "code" && method !== "link") {
+            reply.code(400).send(fail("method must be 'code' or 'link'"));
+            return;
+        }
+
+        if (method === "link" && !cfg.link_base_url) {
+            reply.code(400).send(fail("link_base_url is not configured"));
+            return;
+        }
+
+        if (isRateLimited(email, cfg.rate_limit.per_email_per_hour)) {
+            reply.code(429).send(fail("발송 제한 횟수를 초과했습니다."));
+            return;
+        }
+
+        // 계정 조회 (열거 공격 방지 — 동일 응답)
+        const account = await findAccountByEmail(email);
+        if (!account || !account.seq) {
+            reply.send(ok({ message: "인증 이메일을 발송했습니다." }));
+            return;
+        }
+
+        if (account.email_verified) {
+            reply.send(ok({ message: "이미 인증된 이메일입니다." }));
+            return;
+        }
+
+        // 재발송 쿨다운 체크
+        if (account.email_verify_expires_time) {
+            const lastSentAt =
+                new Date(account.email_verify_expires_time).getTime() -
+                cfg.code_ttl_sec * 1000;
+            const cooldownEnd = lastSentAt + cfg.resend_cooldown_sec * 1000;
+            if (Date.now() < cooldownEnd) {
+                reply
+                    .code(429)
+                    .send(
+                        fail(
+                            "재발송 쿨다운 중입니다. 잠시 후 다시 시도하세요.",
+                        ),
+                    );
+                return;
+            }
+        }
+
+        try {
+            await sendVerification(cfg, account.seq, email, method);
+        } catch (err) {
+            logger.error({ err, email }, "Email verification send failed");
+            // 열거 공격 방지 — 에러도 동일 응답
+        }
+
+        reply.send(ok({ message: "인증 이메일을 발송했습니다." }));
+    };
+}
+
+/**
+ * 공통: 인증 코드/링크 생성 + 저장 + 이메일 발송
+ *
+ * register 등 다른 라우트에서도 재사용 가능.
+ * email-verify config를 주입받아 동일한 방식으로 발송한다.
+ */
+export async function sendVerification(
+    cfg: EmailVerifyConfig,
+    accountSeq: number,
+    email: string,
+    method: "code" | "link",
+): Promise<void> {
+    const expiresAt = new Date(
+        Date.now() + cfg.code_ttl_sec * 1000,
+    ).toISOString();
+    const expiresMin = Math.ceil(cfg.code_ttl_sec / 60);
+
+    if (method === "link") {
+        const token = generateRandomToken();
+        const tokenHash = hashVerificationValue(token);
+
+        await entityServer.submit("account", {
+            seq: accountSeq,
+            email_verify_code: tokenHash,
+            email_verify_expires_time: expiresAt,
+            email_verify_attempts: 0,
+        } as Record<string, unknown>);
+
+        const activationUrl = `${cfg.link_base_url}?email=${encodeURIComponent(email)}&token=${token}`;
+        await sendEmail({
+            to: [email],
+            subject: cfg.email_subject || "이메일 인증",
+            templateDir: TEMPLATES_DIR,
+            templateName: "verification_link",
+            templateData: {
+                activation_url: activationUrl,
+                expires_in: `${expiresMin}분`,
+                email,
+            },
+        });
+    } else {
+        const code = generateNumericCode(cfg.code_length || 6);
+        const codeHash = hashVerificationValue(code);
+
+        await entityServer.submit("account", {
+            seq: accountSeq,
+            email_verify_code: codeHash,
+            email_verify_expires_time: expiresAt,
+            email_verify_attempts: 0,
+        } as Record<string, unknown>);
+
+        await sendEmail({
+            to: [email],
+            subject: cfg.email_subject || "이메일 인증",
+            templateDir: TEMPLATES_DIR,
+            templateName: "verification",
+            templateData: { code, expires_in: `${expiresMin}분`, email },
+        });
+    }
+
+    logger.info({ accountSeq, method }, "Verification email sent");
+}

package/src/app/routes/email-verify/handlers/status.ts

@@ -0,0 +1,53 @@
+/**
+ * GET /status — 인증 상태 조회 (JWT 필요)
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import type { EmailVerifyConfig } from "../types/index.ts";
+import { getAccountSeqFromJwt, getAccountBySeq } from "./utils.ts";
+
+export function createStatusHandler(cfg: EmailVerifyConfig) {
+    return async function handleStatus(
+        req: FastifyRequest,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const accountSeq = getAccountSeqFromJwt(req);
+        if (!accountSeq) {
+            reply.code(401).send(fail("인증이 필요합니다."));
+            return;
+        }
+
+        const account = await getAccountBySeq(accountSeq);
+        if (!account) {
+            reply.code(404).send(fail("계정을 찾을 수 없습니다."));
+            return;
+        }
+
+        let canResend = true;
+        let resendAvailableAt: string | undefined;
+
+        if (account.email_verify_expires_time) {
+            const lastSentAt =
+                new Date(account.email_verify_expires_time).getTime() -
+                cfg.code_ttl_sec * 1000;
+            const cooldownEnd = lastSentAt + cfg.resend_cooldown_sec * 1000;
+            if (Date.now() < cooldownEnd) {
+                canResend = false;
+                resendAvailableAt = new Date(cooldownEnd).toISOString();
+            }
+        }
+
+        reply.send(
+            ok({
+                email: account.email,
+                email_verified: !!account.email_verified,
+                required: cfg.required,
+                can_resend: canResend,
+                ...(resendAvailableAt
+                    ? { resend_available_at: resendAvailableAt }
+                    : {}),
+            }),
+        );
+    };
+}

package/src/app/routes/email-verify/handlers/utils.ts

@@ -0,0 +1,85 @@
+/**
+ * email-verify 공통 유틸리티
+ *
+ * - Rate Limit (인메모리 슬라이딩 윈도우)
+ * - JWT에서 account_seq 추출
+ * - account 엔티티 조회 헬퍼
+ */
+
+import type { FastifyRequest } from "fastify";
+import { entityServer } from "@gateway/api";
+import type { AccountVerifyFields, RateLimitEntry } from "../types/index.ts";
+
+/* ──────────── 상수 ──────────── */
+
+export const MAX_EMAIL_LEN = 320;
+const HOUR_MS = 3_600_000;
+
+/* ──────────── Rate Limit ──────────── */
+
+const emailRateLimits = new Map<string, RateLimitEntry>();
+
+export function isRateLimited(email: string, maxPerHour: number): boolean {
+    const now = Date.now();
+    const entry = emailRateLimits.get(email);
+    if (!entry) {
+        emailRateLimits.set(email, { timestamps: [now] });
+        return false;
+    }
+    entry.timestamps = entry.timestamps.filter((t) => t > now - HOUR_MS);
+    if (entry.timestamps.length >= maxPerHour) return true;
+    entry.timestamps.push(now);
+    return false;
+}
+
+// 5분마다 만료 항목 정리
+const _cleanup = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of emailRateLimits) {
+        entry.timestamps = entry.timestamps.filter((t) => t > now - HOUR_MS);
+        if (entry.timestamps.length === 0) emailRateLimits.delete(key);
+    }
+}, 5 * 60_000);
+if (_cleanup.unref) _cleanup.unref();
+
+/* ──────────── 공통 유틸 ──────────── */
+
+export function nowIsoString(): string {
+    return new Date().toISOString();
+}
+
+/** JWT에서 account_seq 추출 (프록시 인증 헤더 기반) */
+export function getAccountSeqFromJwt(req: FastifyRequest): number | null {
+    const user = (req as unknown as Record<string, unknown>).user as
+        | Record<string, unknown>
+        | undefined;
+    if (!user) return null;
+    return Number(user.account_seq ?? user.seq ?? 0) || null;
+}
+
+export async function findAccountByEmail(
+    email: string,
+): Promise<AccountVerifyFields | null> {
+    try {
+        const result = await entityServer.find<AccountVerifyFields>("account", {
+            email,
+        });
+        return result?.data ?? null;
+    } catch {
+        return null;
+    }
+}
+
+export async function getAccountBySeq(
+    seq: number,
+): Promise<AccountVerifyFields | null> {
+    try {
+        const result = await entityServer.get<AccountVerifyFields>(
+            "account",
+            seq,
+        );
+        return result?.data ?? null;
+    } catch {
+        return null;
+    }
+}

package/src/app/routes/email-verify/routes.ts

@@ -0,0 +1,54 @@
+/**
+ * 이메일 인증 라우트 플러그인
+ *
+ * 자동 로더가 `app/routes/email-verify/routes.ts`를 탐색하여
+ * prefix `/api/v1/email-verify` 으로 등록한다.
+ *
+ * 엔드포인트:
+ *   POST /send              — 인증 코드/링크 발송 (비보호)
+ *   POST /confirm           — 코드 검증 (비보호)
+ *   GET  /activate          — 링크 클릭 인증 (비보호)
+ *   GET  /status            — 인증 상태 조회 (JWT 필요)
+ *   POST /change            — 이메일 변경 + 재인증 (JWT 필요)
+ */
+
+import type { FastifyInstance } from "fastify";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import { ensurePluginEntities } from "@gateway/api";
+import { loadEmailVerifyConfig } from "./config-loader.ts";
+import {
+    createSendHandler,
+    createConfirmHandler,
+    createActivateHandler,
+    createStatusHandler,
+    createChangeHandler,
+} from "./handlers/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const suppressRouteRegisterLog = true;
+
+export default async function emailVerifyRoutes(
+    app: FastifyInstance,
+): Promise<void> {
+    const cfg = loadEmailVerifyConfig();
+
+    if (!cfg.enabled) {
+        return;
+    }
+
+    await ensurePluginEntities(__dirname).catch((err) =>
+        logger.warn({ err }, "email-verify: ensureEntities failed"),
+    );
+
+    // 비보호 엔드포인트
+    app.post("/send", createSendHandler(cfg));
+    app.post("/confirm", createConfirmHandler(cfg));
+    app.get("/activate", createActivateHandler(cfg));
+
+    // JWT 필요 엔드포인트
+    app.get("/status", createStatusHandler(cfg));
+    app.post("/change", createChangeHandler(cfg));
+}

package/src/app/routes/email-verify/templates/verification.html

@@ -0,0 +1,15 @@
+<h2 style="margin: 0 0 16px; font-size: 22px; font-weight: 700; color: #1a1a2e;">이메일 인증</h2>
+<p style="margin: 0 0 24px; font-size: 15px; color: #555; line-height: 1.6;">
+    아래 인증 코드를 입력하여 이메일을 인증하세요.
+</p>
+<div style="text-align: center; margin: 0 0 28px;">
+    <div style="display: inline-block; padding: 14px 32px; background-color: #f4f4f7; border-radius: 8px; border: 1px solid #e0e0e0;">
+        <span style="font-size: 28px; font-weight: 700; letter-spacing: 8px; color: #1a1a2e; font-family: 'Courier New', Courier, monospace;">${code|000000}</span>
+    </div>
+</div>
+<p style="margin: 0 0 8px; font-size: 14px; color: #888; line-height: 1.6;">
+    이 코드는 <strong>${expires_in|5분}</strong> 동안 유효합니다.
+</p>
+<p style="margin: 0; font-size: 13px; color: #aaa; line-height: 1.6;">
+    본인이 요청하지 않은 경우 이 이메일을 무시하세요.
+</p>