create-entity-app-server 0.0.3

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

@@ -0,0 +1,281 @@
+/**
+ * 패킷 암호화 미들웨어 플러그인
+ *
+ * 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

@@ -0,0 +1,18 @@
+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: 중복 로깅 제거)
+});

package/src/system/plugins/access-log.ts

@@ -0,0 +1,34 @@
+/**
+ * Access Log 플러그인 — HTTP 요청/응답을 access.log 파일에 기록
+ *
+ * server.json의 logging.access.enabled 가 true 일 때만 활성화됩니다.
+ * 기록 항목: method, url, statusCode, 응답시간(ms), IP, requestId, User-Agent
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { accessLogger } from "../logging/logger.ts";
+import { parseUserAgent } from "../utils/user-agent.ts";
+
+export default fp(async (app: FastifyInstance) => {
+    if (!accessLogger) return;
+
+    const logger = accessLogger;
+    app.addHook("onResponse", (request, reply, done) => {
+        const userAgent = parseUserAgent(request.headers["user-agent"]);
+        logger.info({
+            requestId: request.id,
+            method: request.method,
+            url: request.url,
+            statusCode: reply.statusCode,
+            responseTime: Math.round(reply.elapsedTime),
+            ip: request.ip,
+            userAgent: userAgent.raw || null,
+            platform: userAgent.platform ?? null,
+            deviceType: userAgent.deviceType ?? null,
+            browser: userAgent.browser ?? null,
+            browserVersion: userAgent.browserVersion ?? null,
+        });
+        done();
+    });
+});

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

@@ -0,0 +1,281 @@
+/**
+ * 패킷 암호화 미들웨어 플러그인
+ *
+ * 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/proxy/register.ts

@@ -0,0 +1,37 @@
+import type { FastifyInstance } from "fastify";
+import { env } from "../config/env.ts";
+
+/** 경로별 타임아웃 정책 (ms) — rewritePrefix 생략 시 /v1/{prefix} 로 자동 변환 */
+const PROXY_ROUTES: Array<{
+    prefix: string;
+    timeout: number;
+    rewritePrefix?: string;
+    methods?: string[];
+}> = [
+    { prefix: "auth", timeout: 10_000 },
+    // oauth redirect/callback → 게이트웨이(/api/v1/oauth/*)로 이관됨
+    { prefix: "entity", timeout: 30_000 }, // 무거운 쿼리 고려
+    { prefix: "files", timeout: 60_000 }, // 파일 업/다운로드
+    { prefix: "push", timeout: 10_000 },
+    { prefix: "smtp", timeout: 15_000 },
+    { prefix: "utils", timeout: 10_000 },
+];
+
+/** Entity Server 프록시 라우트를 일괄 등록한다 */
+export async function registerProxyRoutes(app: FastifyInstance) {
+    for (const { prefix, timeout, rewritePrefix, methods } of PROXY_ROUTES) {
+        await app.register(import("@fastify/http-proxy"), {
+            upstream: env.ENTITY_SERVER_URL,
+            prefix: `/api/v1/${prefix}`,
+            rewritePrefix: rewritePrefix ?? `/v1/${prefix}`,
+            http2: false,
+            httpMethods: methods ?? ["GET", "POST", "PUT", "PATCH", "DELETE"],
+            replyOptions: {
+                timeout,
+                onError: (_reply, error) => {
+                    throw error; // error-handler.ts 가 처리
+                },
+            },
+        });
+    }
+}