create-entity-app-server 0.0.4 → 0.1.13

package/dist-create/template/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/dist-create/template/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/dist-create/template/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>

package/dist-create/template/app/routes/email-verify/templates/verification_link.html

@@ -0,0 +1,19 @@
+<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 24px;">
+    <a href="${activation_url|#}" style="display: inline-block; padding: 14px 36px; background-color: #1a1a2e; color: #ffffff; text-decoration: none; border-radius: 6px; font-size: 15px; font-weight: 600;">이메일 인증하기</a>
+</div>
+<p style="margin: 0 0 8px; font-size: 14px; color: #888; line-height: 1.6;">
+    버튼이 작동하지 않으면 아래 링크를 브라우저에 붙여넣으세요:
+</p>
+<p style="margin: 0 0 16px; font-size: 13px; color: #4a90d9; word-break: break-all; line-height: 1.6;">
+    ${activation_url|#}
+</p>
+<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>

package/dist-create/template/app/routes/email-verify/types/index.ts

@@ -0,0 +1,77 @@
+/**
+ * 이메일 인증 — 요청/응답 타입 정의
+ */
+
+/* ──────────── 설정 ──────────── */
+
+export interface EmailVerificationRateLimitConfig {
+    /** 동일 이메일 시간당 최대 요청 수 (기본 5) */
+    per_email_per_hour: number;
+}
+
+export interface EmailVerifyConfig {
+    /** 기능 활성화 여부 */
+    enabled: boolean;
+    /** 미인증 계정 로그인 차단 여부 */
+    required: boolean;
+    /** 인증 코드 길이 (기본 6) */
+    code_length: number;
+    /** 코드/토큰 유효 시간(초), 기본 300 (5분) */
+    code_ttl_sec: number;
+    /** 최대 시도 횟수 (기본 5) */
+    max_attempts: number;
+    /** 재발송 쿨다운(초), 기본 60 */
+    resend_cooldown_sec: number;
+    /** 링크 인증 기본 URL (link 방식 전용) */
+    link_base_url: string;
+    /** Rate limit 설정 */
+    rate_limit: EmailVerificationRateLimitConfig;
+    /** 이메일 제목 */
+    email_subject: string;
+    /** 빌드 시 dist에 포함 여부 (기본: true, false면 배포에서 제외) */
+    deploy?: boolean;
+    /** 빌드 시 난독화 여부 */
+    minify?: boolean;
+}
+
+/* ──────────── 요청 ──────────── */
+
+export interface VerificationSendBody {
+    email: string;
+    /** "code" (기본값) | "link" */
+    method?: "code" | "link";
+}
+
+export interface VerificationConfirmBody {
+    email: string;
+    code: string;
+}
+
+export interface VerificationActivateQuery {
+    email: string;
+    token: string;
+    redirect?: string;
+}
+
+export interface EmailChangeBody {
+    new_email: string;
+    current_password?: string;
+}
+
+/* ──────────── Rate Limit 내부 ──────────── */
+
+export interface RateLimitEntry {
+    timestamps: number[];
+}
+
+/* ──────────── Account 엔티티 필드 ──────────── */
+
+export interface AccountVerifyFields {
+    seq: number;
+    email?: string;
+    email_verified?: boolean;
+    email_verify_code?: string | null;
+    email_verify_expires_time?: string | null;
+    email_verify_attempts?: number | null;
+    passwd?: string;
+}

package/dist-create/template/app/routes/email-verify/verification-utils.ts

@@ -0,0 +1,57 @@
+/**
+ * 이메일 인증 유틸리티
+ *
+ * Go `internal/security/verification.go` 호환:
+ * - N자리 숫자 코드 생성 (crypto.randomInt)
+ * - 32-byte hex 토큰 생성 (crypto.randomBytes)
+ * - SHA-256 해시 + constant-time 비교
+ */
+
+import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
+
+/**
+ * N자리 숫자 인증 코드를 생성한다.
+ *
+ * Go `security.GenerateNumericCode(length)` 호환
+ * @example generateNumericCode(6) → "048291"
+ */
+export function generateNumericCode(length: number): string {
+    const max = 10 ** length;
+    const n = randomInt(max);
+    return String(n).padStart(length, "0");
+}
+
+/**
+ * 32-byte 랜덤 토큰을 생성한다 (링크 인증용).
+ *
+ * @returns 64자 hex 문자열
+ */
+export function generateRandomToken(): string {
+    return randomBytes(32).toString("hex");
+}
+
+/**
+ * 인증값(코드 또는 토큰)의 SHA-256 해시를 생성한다.
+ */
+export function hashVerificationValue(value: string): string {
+    return createHash("sha256")
+        .update(Buffer.from(value, "utf-8"))
+        .digest("hex");
+}
+
+/**
+ * 입력값과 저장된 SHA-256 해시를 constant-time으로 비교한다.
+ *
+ * Go `security.VerifyCode` 호환 (subtle.ConstantTimeCompare)
+ */
+export function verifyCode(input: string, storedHash: string): boolean {
+    const inputHash = hashVerificationValue(input);
+    try {
+        return timingSafeEqual(
+            Buffer.from(inputHash, "hex"),
+            Buffer.from(storedHash, "hex"),
+        );
+    } catch {
+        return false;
+    }
+}

package/dist-create/template/app/routes/example-db/config.json

@@ -0,0 +1,3 @@
+{
+    "enabled": false
+}

package/dist-create/template/app/routes/example-db/handlers.ts

@@ -0,0 +1,220 @@
+/**
+ * DB Example 핸들러 — Kysely DB 직접 접속 예제
+ *
+ * 이 파일은 Gateway에서 DB에 직접 접속하는 방법을 보여줍니다.
+ * req.server.db 가 Kysely<Database> 인스턴스이므로
+ * 체이닝 방식으로 타입 안전한 쿼리를 작성할 수 있습니다.
+ *
+ * ⚠ 주의: database.json 이 설정되어 있어야 동작합니다.
+ *   설정되지 않으면 req.server.db 가 null 이므로 503 에러를 반환합니다.
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import {
+    ok,
+    fail,
+    sql,
+    dbConn,
+    NotFoundError,
+    BadRequestError,
+} from "@gateway/api";
+import type {
+    CreateUserBody,
+    UpdateUserBody,
+    SearchUsersQuery,
+    UserIdParams,
+} from "./types/index.ts";
+// models/users.ts 에서 Database 확장 선언을 로드합니다.
+// 이 import가 있어야 dbConn().selectFrom("users") 에 UsersTable 타입이 적용됩니다.
+import "./models/users.ts";
+
+// ─────────────────────────────────────────────────
+// 기본 CRUD 예제
+// ─────────────────────────────────────────────────
+
+/**
+ * GET /example/users
+ * 사용자 목록 조회 (기본 SELECT)
+ */
+export async function listUsers(req: FastifyRequest, reply: FastifyReply) {
+    const conn = dbConn();
+
+    const users = await conn
+        .selectFrom("users")
+        .select(["seq", "name", "email", "status", "created_time"])
+        .orderBy("seq", "desc")
+        .limit(50)
+        .execute();
+
+    return reply.send(ok(users));
+}
+
+/**
+ * GET /example/users/:id
+ * 사용자 단건 조회
+ */
+export async function getUser(
+    req: FastifyRequest<{ Params: UserIdParams }>,
+    reply: FastifyReply,
+) {
+    const conn = dbConn();
+    const { id } = req.params;
+
+    const user = await conn
+        .selectFrom("users")
+        .selectAll()
+        .where("seq", "=", Number(id))
+        .executeTakeFirst();
+
+    if (!user) {
+        throw new NotFoundError(`User ${id} not found`);
+    }
+
+    return reply.send(ok(user));
+}
+
+/**
+ * POST /example/users
+ * 사용자 생성 (INSERT)
+ */
+export async function createUser(
+    req: FastifyRequest<{ Body: CreateUserBody }>,
+    reply: FastifyReply,
+) {
+    const conn = dbConn();
+    const { name, email, status = "active" } = req.body;
+
+    const result = await conn
+        .insertInto("users")
+        .values({ name, email, status, data: "{}" })
+        .executeTakeFirst();
+
+    return reply.code(201).send(
+        ok({
+            insertId: Number(result.insertId),
+            name,
+            email,
+            status,
+        }),
+    );
+}
+
+/**
+ * PUT /example/users/:id
+ * 사용자 수정 (UPDATE)
+ */
+export async function updateUser(
+    req: FastifyRequest<{ Params: UserIdParams; Body: UpdateUserBody }>,
+    reply: FastifyReply,
+) {
+    const conn = dbConn();
+    const { id } = req.params;
+    const updates = req.body;
+
+    if (!updates || Object.keys(updates).length === 0) {
+        throw new BadRequestError("No fields to update");
+    }
+
+    const result = await conn
+        .updateTable("users")
+        .set(updates)
+        .where("seq", "=", Number(id))
+        .executeTakeFirst();
+
+    if (Number(result.numUpdatedRows) === 0) {
+        throw new NotFoundError(`User ${id} not found`);
+    }
+
+    return reply.send(ok({ id: Number(id), ...updates }));
+}
+
+/**
+ * DELETE /example/users/:id
+ * 사용자 삭제 (DELETE)
+ */
+export async function deleteUser(
+    req: FastifyRequest<{ Params: UserIdParams }>,
+    reply: FastifyReply,
+) {
+    const conn = dbConn();
+    const { id } = req.params;
+
+    const result = await conn
+        .deleteFrom("users")
+        .where("seq", "=", Number(id))
+        .executeTakeFirst();
+
+    if (Number(result.numDeletedRows) === 0) {
+        throw new NotFoundError(`User ${id} not found`);
+    }
+
+    return reply.send(ok({ deleted: true, id: Number(id) }));
+}
+
+// ─────────────────────────────────────────────────
+// 고급 쿼리 예제
+// ─────────────────────────────────────────────────
+
+/**
+ * GET /example/stats
+ * 통계 조회 — raw SQL (sql 태그드 리터럴) 예제
+ *
+ * 복잡한 집계 쿼리나 Database 인터페이스에 등록하지 않은 테이블은
+ * sql`` 태그를 사용하여 raw SQL로 처리합니다.
+ */
+export async function getStats(req: FastifyRequest, reply: FastifyReply) {
+    const conn = dbConn();
+
+    // sql<T>`` 에서 T는 결과 행의 타입
+    const { rows } = await sql<{ status: string; count: number }>`
+        SELECT status, COUNT(*) as count
+        FROM users
+        GROUP BY status
+        ORDER BY count DESC
+    `.execute(conn);
+
+    if (rows.length === 0) {
+        return reply.send(fail("No stats available"));
+    }
+
+    return reply.send(ok(rows));
+}
+
+/**
+ * GET /example/search?q=john&status=active&limit=20&offset=0
+ * 동적 조건 검색 — 조건부 where 체이닝 예제
+ */
+export async function searchUsers(
+    req: FastifyRequest<{ Querystring: SearchUsersQuery }>,
+    reply: FastifyReply,
+) {
+    const conn = dbConn();
+    const { q, status, limit = 20, offset = 0 } = req.query;
+
+    let query = conn
+        .selectFrom("users")
+        .select(["seq", "name", "email", "status", "created_time"]);
+
+    // 검색어가 있으면 이름 또는 이메일에서 LIKE 검색
+    if (q) {
+        query = query.where((eb: any) =>
+            eb.or([
+                eb("name", "like", `%${q}%`),
+                eb("email", "like", `%${q}%`),
+            ]),
+        );
+    }
+
+    // 상태 필터
+    if (status) {
+        query = query.where("status", "=", status);
+    }
+
+    const users = await query
+        .orderBy("seq", "desc")
+        .limit(limit)
+        .offset(offset)
+        .execute();
+
+    return reply.send(ok(users));
+}

package/dist-create/template/app/routes/example-db/models/account-ext.ts

@@ -0,0 +1,33 @@
+/**
+ * account-ext.ts 예제 — 기존 테이블에 플러그인 필드를 추가하는 방법
+ *
+ * Go 서버가 관리하는 account 테이블의 data JSON blob에
+ * 플러그인이 자체 필드를 저장할 때, 타입 안전성을 위해
+ * 아래처럼 AccountExtensions를 확장합니다.
+ *
+ * 실제로 DB를 직접 쓰는 경우에만 필요합니다.
+ * Go API를 통해 account를 읽고 쓴다면 필요하지 않습니다.
+ */
+
+// AccountExtensions 확장 예제
+// declare module "@gateway/api" {
+//     interface AccountExtensions {
+//         my_plugin_enabled?: boolean;   // 플러그인 활성화 여부
+//         my_plugin_data?: string;       // 플러그인 저장 데이터
+//     }
+// }
+// export {};
+
+// AccountTable 자체를 확장하는 예제 (인덱스 컬럼 추가 시)
+// declare module "@gateway/api" {
+//     interface Database {
+//         account: import("kysely").Selectable<{
+//             seq: number;
+//             email: string;
+//             my_index_column: string | null;
+//         }>;
+//     }
+// }
+// export {};
+
+export {};

package/dist-create/template/app/routes/example-db/models/users.ts

@@ -0,0 +1,30 @@
+/**
+ * users 테이블 타입 — Kysely DB 직접 쿼리용
+ *
+ * DB를 직접 쓸 때만 models/ 폴더에 테이블 타입을 정의합니다.
+ * declare module로 Database에 등록하면 dbConn().selectFrom("users")에서
+ * 자동완성 + 타입 체크가 적용됩니다.
+ *
+ * @see https://kysely.dev/docs/getting-started#types
+ */
+
+import type { Generated } from "kysely";
+
+/** users 테이블 타입 */
+export interface UsersTable {
+    seq: Generated<number>; // PK, auto_increment
+    name: string | null; // 이름
+    email: string; // 이메일 (unique)
+    status: Generated<"active" | "inactive" | null>; // 상태
+    data: Generated<string>; // JSON blob
+    created_time: Generated<string>; // 생성 시각
+    updated_time: Generated<string>; // 수정 시각
+}
+
+declare module "@gateway/api" {
+    interface Database {
+        users: UsersTable;
+    }
+}
+
+export {};

package/dist-create/template/app/routes/example-db/routes.ts

@@ -0,0 +1,23 @@
+/**
+ * DB Example 라우트 테이블
+ * 등록 경로: /api/v1/example-db/*
+ *
+ * Kysely를 사용한 DB 직접 접속 예제입니다.
+ * 실제 프로젝트에서는 이 폴더를 복사하여 새 라우트를 만들 수 있습니다.
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+export default async function dbExampleRoutes(app: FastifyInstance) {
+    // ── 기본 CRUD ──────────────────────────────
+    app.get("/users", h.listUsers);
+    app.get("/users/:id", h.getUser);
+    app.post("/users", h.createUser);
+    app.put("/users/:id", h.updateUser);
+    app.delete("/users/:id", h.deleteUser);
+
+    // ── 고급 쿼리 ─────────────────────────────
+    app.get("/stats", h.getStats);
+    app.get("/search", h.searchUsers);
+}

package/dist-create/template/app/routes/example-db/types/defaults.ts

@@ -0,0 +1,21 @@
+import type { CreateUserBody, UpdateUserBody } from "./user.ts";
+import type { SearchUsersQuery } from "./query.ts";
+
+export const defaultCreateUserBody: CreateUserBody = {
+    name: "",
+    email: "",
+    status: "active",
+};
+
+export const defaultUpdateUserBody: UpdateUserBody = {
+    name: undefined,
+    email: undefined,
+    status: undefined,
+};
+
+export const defaultSearchUsersQuery: SearchUsersQuery = {
+    q: undefined,
+    status: undefined,
+    limit: 20,
+    offset: 0,
+};

package/dist-create/template/app/routes/example-db/types/index.ts

@@ -0,0 +1,4 @@
+export type { CreateUserBody, UpdateUserBody } from "./user.ts";
+export type { UserIdParams } from "./params.ts";
+export type { SearchUsersQuery } from "./query.ts";
+export * from "./defaults.ts";

package/dist-create/template/app/routes/example-db/types/params.ts

@@ -0,0 +1,3 @@
+export interface UserIdParams {
+    id: string;
+}

package/dist-create/template/app/routes/example-db/types/query.ts

@@ -0,0 +1,6 @@
+export interface SearchUsersQuery {
+    q?: string;
+    status?: "active" | "inactive";
+    limit?: number;
+    offset?: number;
+}

package/dist-create/template/app/routes/example-db/types/user.ts

@@ -0,0 +1,11 @@
+export interface CreateUserBody {
+    name: string;
+    email: string;
+    status?: "active" | "inactive";
+}
+
+export interface UpdateUserBody {
+    name?: string;
+    email?: string;
+    status?: "active" | "inactive";
+}

package/dist-create/template/app/routes/example-es/config.json

@@ -0,0 +1,3 @@
+{
+    "enabled": false
+}