create-entity-app-server 0.0.4 → 0.1.13

package/dist-create/template/app/routes/email-verify/config-loader.ts

@@ -0,0 +1,47 @@
+/**
+ * email-verify 설정 로더
+ *
+ * `router.ts`와 외부 모듈(register 등) 모두에서 재사용하기 위해
+ * 별도 파일로 분리.
+ *
+ * Usage:
+ *   import { loadEmailVerifyConfig } from "../../email-verify/config-loader.ts";
+ *   const cfg = loadEmailVerifyConfig();
+ *   if (cfg.enabled) { ... }
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { EmailVerifyConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** email-verify/config.json 로드 + 기본값 보정 */
+export function loadEmailVerifyConfig(): EmailVerifyConfig {
+    const configPath = resolve(__dirname, "config.json");
+    let raw: Record<string, unknown> = {};
+    if (existsSync(configPath)) {
+        const text = readFileSync(configPath, "utf-8").replace(
+            /\$\{([^}]+)\}/g,
+            (_m, name) => process.env[name] ?? "",
+        );
+        raw = JSON.parse(text) as Record<string, unknown>;
+    }
+
+    const rl = (raw.rate_limit ?? {}) as Record<string, unknown>;
+
+    return {
+        enabled: raw.enabled !== false,
+        required: raw.required === true,
+        code_length: Number(raw.code_length) || 6,
+        code_ttl_sec: Number(raw.code_ttl_sec) || 300,
+        max_attempts: Number(raw.max_attempts) || 5,
+        resend_cooldown_sec: Number(raw.resend_cooldown_sec) || 60,
+        link_base_url: String(raw.link_base_url ?? ""),
+        rate_limit: {
+            per_email_per_hour: Number(rl.per_email_per_hour) || 5,
+        },
+        email_subject: String(raw.email_subject ?? "이메일 인증"),
+    };
+}

package/dist-create/template/app/routes/email-verify/config.json

@@ -0,0 +1,13 @@
+{
+    "enabled": true,
+    "required": false,
+    "code_length": 6,
+    "code_ttl_sec": 300,
+    "max_attempts": 5,
+    "resend_cooldown_sec": 60,
+    "link_base_url": "https://example.com/verify-email",
+    "rate_limit": {
+        "per_email_per_hour": 5
+    },
+    "email_subject": "이메일 인증"
+}

package/dist-create/template/app/routes/email-verify/entities/account.json

@@ -0,0 +1,23 @@
+{
+    "name": "account",
+    "description": "이메일 인증(email-verify) 라우트 전용 필드. email_verified 상태에 따른 처리(인증 메일 발송/검증/차단)는 앱서버 email-verify 라우트가 담당합니다.",
+    "fields": {
+        "email_verified": {
+            "type": "bool",
+            "default": false,
+            "comment": "이메일 인증 완료 여부"
+        },
+        "email_verify_code": {
+            "type": "varchar(64)",
+            "comment": "인증 코드 SHA-256 해시"
+        },
+        "email_verify_expires_time": {
+            "comment": "인증 코드 만료 시각 (RFC3339)"
+        },
+        "email_verify_attempts": {
+            "type": "uint",
+            "default": 0,
+            "comment": "이메일 인증 시도 횟수"
+        }
+    }
+}

package/dist-create/template/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/dist-create/template/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/dist-create/template/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/dist-create/template/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/dist-create/template/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/dist-create/template/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 }
+                    : {}),
+            }),
+        );
+    };
+}