create-entity-app-server 0.0.3 → 0.0.4

package/src/system/middleware/csrf.ts

@@ -1,172 +0,0 @@
-/**
- * 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

@@ -1,44 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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

@@ -1,111 +0,0 @@
-/**
- * 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;
-}

package/src/system/middleware/packet-encrypt.ts

@@ -1,281 +0,0 @@
-/**
- * 패킷 암호화 미들웨어 플러그인
- *
- * Go Entity Server의 internal/middleware/packet_encrypt.go를 Fastify로 포팅.
- *
- * 동작:
- * [요청 복호화]
- *   - 인증된 사용자의 POST/PUT/DELETE 요청이 Content-Type: application/octet-stream이면 복호화
- *   - require_encryption=true 시 인증된 요청의 평문 JSON을 거부 (400)
- *   - GET/HEAD/OPTIONS는 건너뜀
- *
- * [응답 암호화]
- *   - 2xx 성공 응답만 암호화
- *   - 4xx/5xx 에러는 평문 JSON 유지
- *
- * 키 파생:
- *   - JWT 인증:  HKDF-SHA256(jwt_token,  "entity-server:packet-encryption")
- *   - HMAC 인증: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
- */
-
-import fp from "fastify-plugin";
-import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
-import { env, logger } from "../config/env.ts";
-import { cache } from "../cache/index.ts";
-import {
-    derivePacketKey,
-    deriveKey32HKDF,
-    packetMagicLenFromKey,
-    encryptPacket,
-    decryptPacket,
-} from "../crypto/packet.ts";
-import {
-    loadPacketEncryptConfig,
-    type PacketEncryptConfig,
-} from "../config/packet-encrypt.ts";
-import { readAnonymousDeviceId } from "../security/anonymous-device-id.ts";
-import { deriveAnonymousPacketToken } from "../security/anonymous-packet-token.ts";
-
-const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
-
-/**
- * 요청에서 패킷 키를 유도합니다.
- * JWT 토큰이 있으면 JWT 기반, 없으면 HMAC secret 기반.
- */
-async function deriveKeyForRequest(
-    req: FastifyRequest,
-    infoLabel: string,
-    anonymousDeviceId?: string | null,
-): Promise<Buffer | null> {
-    const authHeader = req.headers.authorization;
-    if (authHeader?.startsWith("Bearer ")) {
-        const token = authHeader.substring(7);
-        // infoLabel을 cfg에서 받아 사용 (hardcoded "entity-server:packet-encryption" 제거)
-        return derivePacketKey(token, infoLabel);
-    }
-
-    // HMAC 인증 (API key)
-    if (req.headers["x-api-key"]) {
-        return deriveKey32HKDF(env.ENTITY_HMAC_SECRET, infoLabel);
-    }
-
-    const packetTokenHeader = req.headers["x-packet-token"];
-    const packetToken = Array.isArray(packetTokenHeader)
-        ? packetTokenHeader[0]
-        : packetTokenHeader;
-    if (packetToken) {
-        return derivePacketKey(packetToken, infoLabel);
-    }
-
-    if (anonymousDeviceId) {
-        const packetToken = deriveAnonymousPacketToken(
-            anonymousDeviceId,
-            infoLabel,
-        );
-        return derivePacketKey(packetToken, infoLabel);
-    }
-
-    return null;
-}
-
-async function resolvePacketKey(
-    req: FastifyRequest,
-    cfg: PacketEncryptConfig,
-): Promise<Buffer | null> {
-    const authHeader = req.headers.authorization;
-    const apiKey = req.headers["x-api-key"] as string | undefined;
-    const packetTokenHeader = req.headers["x-packet-token"];
-    const packetToken = Array.isArray(packetTokenHeader)
-        ? packetTokenHeader[0]
-        : packetTokenHeader;
-    const anonymousDeviceId = readAnonymousDeviceId(req, cfg);
-    const keyCacheId =
-        authHeader ??
-        (apiKey
-            ? `hmac:${apiKey}`
-            : packetToken
-              ? `anon-token:${packetToken}`
-              : anonymousDeviceId
-                ? `anon:${anonymousDeviceId}`
-                : null);
-
-    if (!keyCacheId) {
-        return null;
-    }
-
-    const store = cache();
-    const cacheKey = `pkt_key:${keyCacheId}`;
-    const cachedB64 = await store.get<string>(cacheKey);
-    if (cachedB64) {
-        return Buffer.from(cachedB64, "base64");
-    }
-
-    const key = await deriveKeyForRequest(
-        req,
-        cfg.infoLabel,
-        anonymousDeviceId,
-    );
-    if (key) {
-        await store.set(cacheKey, key.toString("base64"), 5 * 60 * 1000);
-    }
-
-    return key;
-}
-
-export default fp(async (app: FastifyInstance) => {
-    const cfg = loadPacketEncryptConfig();
-
-    if (!cfg.enabled) {
-        return;
-    }
-
-    app.addContentTypeParser(
-        "application/octet-stream",
-        { parseAs: "buffer" },
-        (req, body, done) => {
-            const rawBody = Buffer.isBuffer(body) ? body : Buffer.from(body);
-            req.rawBody = rawBody;
-            done(null, rawBody);
-        },
-    );
-
-    // ─── 요청 복호화 (preValidation) ───
-    app.addHook(
-        "preValidation",
-        async (req: FastifyRequest, reply: FastifyReply) => {
-            // skip paths 스킵
-            const urlPath = req.url.split("?")[0];
-            for (const skip of cfg.skipPaths) {
-                if (urlPath.startsWith(skip)) return;
-            }
-
-            const key = await resolvePacketKey(req, cfg);
-            if (!key) return;
-
-            req._packetKey = key;
-
-            // safe methods는 요청 본문 복호화만 생략하고 응답 암호화는 유지
-            if (SAFE_METHODS.has(req.method)) return;
-
-            const contentType = (
-                req.headers["content-type"] ?? ""
-            ).toLowerCase();
-            const rawBody =
-                req.rawBody ??
-                (Buffer.isBuffer(req.body)
-                    ? req.body
-                    : req.body instanceof Uint8Array
-                      ? Buffer.from(req.body)
-                      : undefined);
-
-            if (!rawBody || rawBody.length === 0) return;
-
-            if (contentType.includes("application/octet-stream")) {
-                // 암호화된 요청 → 복호화
-                const magicLen = packetMagicLenFromKey(
-                    key,
-                    cfg.magicMin,
-                    cfg.magicRange,
-                );
-                try {
-                    const plaintext = await decryptPacket(
-                        rawBody,
-                        key,
-                        magicLen,
-                    );
-                    // 복호화된 body를 요청에 주입
-                    req.rawBody = plaintext;
-                    (req as any).body = JSON.parse(plaintext.toString());
-                    req.headers["content-type"] = "application/json";
-                } catch (err) {
-                    logger.warn(
-                        { error: (err as Error).message, url: req.url },
-                        "Request decryption failed",
-                    );
-                    return reply.code(400).send({
-                        success: false,
-                        error: "Request decryption failed",
-                    });
-                }
-            } else if (
-                cfg.requireEncryption &&
-                contentType.includes("application/json")
-            ) {
-                // 평문 JSON → 암호화 필수 위반
-                return reply.code(400).send({
-                    success: false,
-                    error: "Encrypted request required",
-                });
-            }
-        },
-    );
-
-    // ─── 응답 암호화 (onSend) ───
-    app.addHook(
-        "onSend",
-        async (req: FastifyRequest, reply: FastifyReply, payload: unknown) => {
-            if ((req as any)._packetResponseHandled) return payload;
-
-            // 패킷 키가 없으면 (복호화하지 않은 요청) 건너뜀
-            const key = req._packetKey;
-            if (!key) return payload;
-
-            // 2xx만 암호화
-            const status = reply.statusCode;
-            if (status < 200 || status >= 300) return payload;
-            if (payload == null) return payload;
-
-            try {
-                // payload를 Buffer로 변환
-                let plaintext: Buffer;
-                if (typeof payload === "string") {
-                    plaintext = Buffer.from(payload);
-                } else if (Buffer.isBuffer(payload)) {
-                    plaintext = payload;
-                } else if (payload instanceof Uint8Array) {
-                    plaintext = Buffer.from(payload);
-                } else {
-                    const serialized = JSON.stringify(payload);
-                    if (serialized == null) {
-                        return payload;
-                    }
-                    plaintext = Buffer.from(serialized);
-                }
-
-                if (plaintext.length === 0) return payload;
-
-                const magicLen = packetMagicLenFromKey(
-                    key,
-                    cfg.magicMin,
-                    cfg.magicRange,
-                );
-                const encrypted = await encryptPacket(plaintext, key, magicLen);
-
-                reply.header("content-type", "application/octet-stream");
-                return encrypted;
-            } catch (err) {
-                logger.error(
-                    {
-                        error: (err as Error).message,
-                        stack: (err as Error).stack,
-                        payloadType:
-                            payload == null
-                                ? String(payload)
-                                : Buffer.isBuffer(payload)
-                                  ? "buffer"
-                                  : typeof payload,
-                        responseContentType: reply.getHeader("content-type"),
-                    },
-                    "Response encryption failed",
-                );
-                // 암호화 실패 → 평문 노출 방지를 위해 에러 반환
-                reply.code(500);
-                reply.header("content-type", "application/json; charset=utf-8");
-                return JSON.stringify({
-                    success: false,
-                    error: "Response encryption failed",
-                });
-            }
-        },
-    );
-});

package/src/system/middleware/request-id.ts

@@ -1,18 +0,0 @@
-import fp from "fastify-plugin";
-import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
-import { v4 as uuidv4 } from "uuid";
-
-/** 요청 ID 플러그인 — X-Request-ID 헤더 관리 */
-export default fp(async (app: FastifyInstance) => {
-    app.addHook(
-        "onRequest",
-        async (req: FastifyRequest, reply: FastifyReply) => {
-            // Nginx가 전달한 X-Request-ID가 없으면 직접 생성
-            const requestId =
-                (req.headers["x-request-id"] as string) ?? uuidv4();
-            req.headers["x-request-id"] = requestId;
-            reply.header("X-Request-ID", requestId);
-        },
-    );
-    // 응답 로깅은 access-log 플러그인에서 전담 (D6: 중복 로깅 제거)
-});