create-entity-app-server 0.0.3

package/src/system/middleware/auth.ts

@@ -0,0 +1,67 @@
+import { createHash } from "crypto";
+import fp from "fastify-plugin";
+import jwt from "jsonwebtoken";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import type { UserInfo } from "../hooks/types.ts";
+import { env } from "../config/env.ts";
+import { cache } from "../cache/index.ts";
+
+/** JWT 인증 플러그인 — 토큰 디코드 및 검증 */
+export default fp(async (app: FastifyInstance) => {
+    app.decorateRequest("user", null);
+
+    // 전역 hook: 디코드만 — 프록시 라우트는 Entity Server가 검증
+    app.addHook("onRequest", async (req: FastifyRequest) => {
+        const token = req.headers.authorization?.replace("Bearer ", "");
+        if (token) {
+            try {
+                req.user = jwt.decode(token) as unknown as UserInfo;
+            } catch {
+                // 무시 — 프록시에서 Entity Server가 거부함
+            }
+        }
+    });
+
+    // 비즈니스 라우트 preHandler: 서명 검증 + 만료 확인 (검증 결과 캐싱)
+    app.decorate(
+        "authRequired",
+        async (req: FastifyRequest, reply: FastifyReply) => {
+            const token = req.headers.authorization?.replace("Bearer ", "");
+            if (!token) {
+                return reply.code(401).send({ error: "Unauthorized" });
+            }
+            try {
+                // 캐시 조회 — 동일 토큰의 검증 결과 재사용 (crypto 연산 절감)
+                const store = cache();
+                const cacheKey = `auth:${createHash("sha256").update(token).digest("hex")}`;
+                const cached = await store.get<UserInfo>(cacheKey);
+                if (cached) {
+                    req.user = cached;
+                    return;
+                }
+
+                const user = jwt.verify(
+                    token,
+                    env.JWT_SECRET,
+                ) as unknown as UserInfo;
+
+                // TTL: 토큰 만료까지 남은 시간, exp 없으면 5분
+                const exp = (user as unknown as { exp?: number }).exp;
+                const ttlMs = exp
+                    ? Math.max(0, (exp - Math.floor(Date.now() / 1000)) * 1000)
+                    : 5 * 60 * 1000;
+
+                // TTL > 0 일 때만 캐싱 (이미 만료 직전 토큰은 캐싱 불필요)
+                if (ttlMs > 1000) {
+                    await store.set(cacheKey, user, ttlMs);
+                }
+
+                req.user = user;
+            } catch {
+                return reply
+                    .code(401)
+                    .send({ error: "Invalid or expired token" });
+            }
+        },
+    );
+});

package/src/system/middleware/csrf.ts

@@ -0,0 +1,172 @@
+/**
+ * CSRF 보안 플러그인 — Double Submit Cookie 패턴
+ *
+ * 동작 방식:
+ * 1. GET /csrf-token → 랜덤 토큰 생성 → Set-Cookie + JSON 응답
+ * 2. POST/PUT/DELETE 등 상태변경 요청 시:
+ *    - Cookie의 _csrf 값 vs Header의 x-csrf-token 값 비교
+ *    - 불일치 시 403 Forbidden
+ *
+ * Safe methods(GET, HEAD, OPTIONS)는 검증하지 않습니다.
+ * skip_paths에 지정된 경로는 CSRF 검증을 건너뜁니다.
+ */
+
+import fp from "fastify-plugin";
+import { randomBytes } from "crypto";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { logger } from "../config/env.ts";
+import { loadSecurityJson } from "../config/security-loader.ts";
+
+export interface CsrfConfig {
+    enabled: boolean;
+    cookieName: string;
+    headerName: string;
+    cookieOptions: {
+        httpOnly: boolean;
+        sameSite: "strict" | "lax" | "none";
+        secure: boolean;
+        path: string;
+        maxAge: number;
+    };
+    safeMethods: string[];
+    skipPaths: string[];
+    tokenLength: number;
+}
+
+/** CSRF 보안 설정을 설정 파일에서 로드한다 */
+function loadCsrfConfig(): CsrfConfig {
+    const defaults: CsrfConfig = {
+        enabled: false,
+        cookieName: "_csrf",
+        headerName: "x-csrf-token",
+        cookieOptions: {
+            httpOnly: true,
+            sameSite: "strict",
+            secure: false,
+            path: "/",
+            maxAge: 86400,
+        },
+        safeMethods: ["GET", "HEAD", "OPTIONS"],
+        skipPaths: ["/health"],
+        tokenLength: 32,
+    };
+
+    try {
+        const raw = loadSecurityJson();
+        const c = (raw.csrf ?? {}) as Record<string, any>;
+        return {
+            enabled: c.enabled ?? defaults.enabled,
+            cookieName: c.cookie_name ?? defaults.cookieName,
+            headerName: c.header_name ?? defaults.headerName,
+            cookieOptions: {
+                httpOnly:
+                    c.cookie_options?.http_only ??
+                    defaults.cookieOptions.httpOnly,
+                sameSite:
+                    c.cookie_options?.same_site ??
+                    defaults.cookieOptions.sameSite,
+                secure:
+                    c.cookie_options?.secure ?? defaults.cookieOptions.secure,
+                path: c.cookie_options?.path ?? defaults.cookieOptions.path,
+                maxAge:
+                    c.cookie_options?.max_age ?? defaults.cookieOptions.maxAge,
+            },
+            safeMethods: c.safe_methods ?? defaults.safeMethods,
+            skipPaths: c.skip_paths ?? defaults.skipPaths,
+            tokenLength: c.token_length ?? defaults.tokenLength,
+        };
+    } catch {
+        return defaults;
+    }
+}
+
+/** 랜덤 CSRF 토큰을 생성한다 */
+function generateToken(length: number): string {
+    return randomBytes(length).toString("hex");
+}
+
+/** Cookie 헤더 문자열을 파싱하여 키-값 객체로 반환한다 */
+function parseCookies(
+    cookieHeader: string | undefined,
+): Record<string, string> {
+    if (!cookieHeader) return {};
+    const result: Record<string, string> = {};
+    for (const pair of cookieHeader.split(";")) {
+        const idx = pair.indexOf("=");
+        if (idx < 0) continue;
+        const key = pair.substring(0, idx).trim();
+        const val = pair.substring(idx + 1).trim();
+        result[key] = decodeURIComponent(val);
+    }
+    return result;
+}
+
+export default fp(async (app: FastifyInstance) => {
+    const cfg = loadCsrfConfig();
+
+    if (!cfg.enabled) {
+        return;
+    }
+
+    logger.info("CSRF protection enabled");
+
+    // ─── GET /csrf-token ─── 토큰 발급 엔드포인트
+    app.get("/csrf-token", async (req: FastifyRequest, reply: FastifyReply) => {
+        const token = generateToken(cfg.tokenLength);
+
+        const cookieParts = [
+            `${cfg.cookieName}=${encodeURIComponent(token)}`,
+            `Path=${cfg.cookieOptions.path}`,
+            `Max-Age=${cfg.cookieOptions.maxAge}`,
+            `SameSite=${cfg.cookieOptions.sameSite.charAt(0).toUpperCase() + cfg.cookieOptions.sameSite.slice(1)}`,
+        ];
+        if (cfg.cookieOptions.httpOnly) cookieParts.push("HttpOnly");
+        if (cfg.cookieOptions.secure) cookieParts.push("Secure");
+
+        reply.header("Set-Cookie", cookieParts.join("; "));
+        return { success: true, data: { token } };
+    });
+
+    // ─── 전역 preHandler: 상태변경 요청에 대해 CSRF 검증 ───
+    app.addHook(
+        "onRequest",
+        async (req: FastifyRequest, reply: FastifyReply) => {
+            // safe methods 스킵
+            if (cfg.safeMethods.includes(req.method)) return;
+
+            // skip paths 스킵
+            const urlPath = req.url.split("?")[0];
+            for (const skip of cfg.skipPaths) {
+                if (urlPath.startsWith(skip)) return;
+            }
+
+            // Bearer 토큰 인증 (API 클라이언트)은 CSRF 면제
+            // — CSRF는 쿠키 기반 자동 전송을 악용하는 공격이므로,
+            //   Authorization 헤더를 명시적으로 보내는 API 클라이언트에는 불필요
+            if (req.headers.authorization) return;
+
+            const cookies = parseCookies(req.headers.cookie);
+            const cookieToken = cookies[cfg.cookieName];
+            const headerToken = req.headers[cfg.headerName] as
+                | string
+                | undefined;
+
+            if (!cookieToken || !headerToken || cookieToken !== headerToken) {
+                logger.warn(
+                    {
+                        method: req.method,
+                        url: req.url,
+                        hasCookie: !!cookieToken,
+                        hasHeader: !!headerToken,
+                    },
+                    "CSRF token mismatch",
+                );
+
+                return reply.code(403).send({
+                    success: false,
+                    error: "CSRF token validation failed",
+                });
+            }
+        },
+    );
+});

package/src/system/middleware/database.ts

@@ -0,0 +1,44 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { loadDatabaseConfig, createKyselyDb } from "../config/database.ts";
+import { logger, logFmt } from "../config/env.ts";
+import { _setDbRef } from "./_db-ref.ts";
+
+/** DB Kysely 플러그인 — 설정 기반으로 Kysely 인스턴스를 생성하여 app.db / app.dbGroups 에 등록 */
+export default fp(async (app: FastifyInstance) => {
+    const config = loadDatabaseConfig();
+    if (!config) {
+        app.decorate("db", null);
+        app.decorate("dbGroups", {});
+        return;
+    }
+
+    // 모든 그룹 커넥션 생성
+    const groups: Record<
+        string,
+        Awaited<ReturnType<typeof createKyselyDb>>
+    > = {};
+    const tableReadOnlyPatterns = config.tableReadOnly ?? [];
+    for (const [name, groupCfg] of Object.entries(config.groups)) {
+        groups[name] = await createKyselyDb(groupCfg, tableReadOnlyPatterns);
+    }
+
+    // default 그룹 → app.db
+    const defaultDb = groups[config.default];
+    if (!defaultDb) {
+        throw new Error(
+            `Database group "${config.default}" not found in database.json`,
+        );
+    }
+
+    app.decorate("db", defaultDb);
+    app.decorate("dbGroups", groups);
+    _setDbRef(defaultDb, groups);
+
+    app.addHook("onClose", async () => {
+        for (const [name, db] of Object.entries(groups)) {
+            await db.destroy();
+            logger.info(logFmt.db(name, "(closed)"));
+        }
+    });
+});

package/src/system/middleware/error-handler.ts

@@ -0,0 +1,51 @@
+import fp from "fastify-plugin";
+import type {
+    FastifyInstance,
+    FastifyRequest,
+    FastifyReply,
+    FastifyError,
+} from "fastify";
+import { logger, isDev } from "../config/env.ts";
+
+function sanitizeUrl(url: string): string {
+    try {
+        const parsed = new URL(url, "http://localhost");
+        for (const key of ["token", "password", "secret", "key"]) {
+            if (parsed.searchParams.has(key)) {
+                parsed.searchParams.set(key, "[REDACTED]");
+            }
+        }
+        return parsed.pathname + parsed.search;
+    } catch {
+        return url;
+    }
+}
+
+/** 전역 에러 핸들러 플러그인 — 에러 로깅 및 표준 응답 포맷 */
+export default fp(async (app: FastifyInstance) => {
+    app.setErrorHandler(
+        (error: FastifyError, req: FastifyRequest, reply: FastifyReply) => {
+            const statusCode = error.statusCode ?? 500;
+            const requestId = req.headers["x-request-id"] ?? "unknown";
+
+            logger.error(
+                {
+                    requestId,
+                    method: req.method,
+                    url: sanitizeUrl(req.url),
+                    statusCode,
+                    error: error.message,
+                    stack: isDev && statusCode >= 500 ? error.stack : undefined,
+                },
+                "Request error",
+            );
+
+            reply.code(statusCode).send({
+                success: false,
+                error:
+                    statusCode >= 500 ? "Internal Server Error" : error.message,
+                requestId,
+            });
+        },
+    );
+});

package/src/system/middleware/extension-loader.ts

@@ -0,0 +1,111 @@
+/**
+ * Plugin 자동 로더
+ *
+ * app/plugins/{module}/index.ts 파일을 자동 탐색하여 Fastify 플러그인을 등록한다.
+ * app.ts의 static import 대신 런타임 동적 import를 사용하여
+ * app/ 소스를 배포 환경에서도 독립적으로 수정 가능하게 한다.
+ */
+
+import { readdirSync, existsSync, readFileSync } from "fs";
+import path from "path";
+import type { FastifyInstance } from "fastify";
+import { logger, logFmt } from "../config/env.ts";
+import { resolveAppRoot } from "../utils/app-path.ts";
+import { resolveModulePath } from "../config/module-path.ts";
+import { substituteEnvVars } from "../config/env-substitution.ts";
+import { batchEnsureAllPluginEntities } from "../entity-server/bootstrap.ts";
+
+function isPluginLogEnabled(modDir: string): boolean {
+    const configPath = path.join(modDir, "config.json");
+    if (!existsSync(configPath)) return true;
+
+    try {
+        const raw = substituteEnvVars(readFileSync(configPath, "utf-8"));
+        const cfg = JSON.parse(raw) as { enabled?: boolean };
+        return cfg.enabled !== false;
+    } catch (err) {
+        logger.warn(
+            { modDir, err },
+            "Failed to parse plugin config while loading extension plugins",
+        );
+        return true;
+    }
+}
+
+/**
+ * app/plugins/ 를 탐색하여 index.ts|js가 있는 모든 플러그인을 등록한다.
+ * 알파벳 순으로 로드하여 결정적(deterministic) 순서를 보장한다.
+ */
+export async function loadExtensionPlugins(
+    app: FastifyInstance,
+): Promise<number> {
+    const appRoot = resolveAppRoot(import.meta.url);
+    const extDir = path.join(appRoot, "plugins");
+    let loadedCount = 0;
+
+    if (!existsSync(extDir)) {
+        logger.warn(
+            { extDir },
+            "app/plugins directory not found, skipping plugins",
+        );
+        return 0;
+    }
+
+    const dirs = readdirSync(extDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+
+    // 플러그인 등록 전 모든 엔티티를 배치로 한 번에 ensure (N개 개별 HTTP → 1개 배치 요청)
+    await batchEnsureAllPluginEntities(
+        dirs.map((name) => path.join(extDir, name)),
+    );
+
+    // 동적 import를 병렬 실행한 뒤 순차 등록 (B3: 직렬 import → 병렬)
+    const loadResults = await Promise.allSettled(
+        dirs.map(async (name) => {
+            const indexPath = resolveModulePath(
+                path.join(extDir, name),
+                "index",
+            );
+            if (!indexPath) return null;
+            const mod = await import(indexPath);
+            return { name, mod };
+        }),
+    );
+
+    const total = loadResults.filter(
+        (r) => r.status === "fulfilled" && r.value?.mod?.default,
+    ).length;
+    const isTTY = process.stdout.isTTY;
+
+    for (const result of loadResults) {
+        if (result.status === "rejected") continue;
+        const entry = result.value;
+        if (!entry) continue;
+
+        try {
+            if (entry.mod.default) {
+                if (isTTY) {
+                    const idx = loadedCount + 1;
+                    process.stdout.write(
+                        `\r  Loading plugins [${idx}/${total}]...`.padEnd(72),
+                    );
+                }
+                await app.register(entry.mod.default);
+                loadedCount++;
+            }
+        } catch (err) {
+            logger.error(
+                { err, name: entry.name },
+                logFmt.error(`Failed to register plugin: ${entry.name}`),
+            );
+        }
+    }
+
+    if (isTTY && total > 0) {
+        process.stdout.write(`\r${" ".repeat(72)}\r`);
+    }
+
+    return loadedCount;
+}