create-entity-app-server 0.0.3 → 0.0.4

package/src/system/config/security.ts

@@ -1,16 +0,0 @@
-import type { FastifyHelmetOptions } from "@fastify/helmet";
-
-export const helmetOptions: FastifyHelmetOptions = {
-    contentSecurityPolicy: {
-        directives: {
-            defaultSrc: ["'self'"],
-            scriptSrc: ["'self'"],
-            styleSrc: ["'self'", "'unsafe-inline'"],
-            imgSrc: ["'self'", "data:", "https:"],
-            connectSrc: ["'self'"],
-            fontSrc: ["'self'"],
-            objectSrc: ["'none'"],
-            frameAncestors: ["'none'"],
-        },
-    },
-};

package/src/system/config/server.ts

@@ -1,81 +0,0 @@
-import { existsSync } from "fs";
-import path from "path";
-import { z } from "zod";
-import dotenv from "dotenv";
-import { resolveConfigsDir } from "./config-path.ts";
-import { loadJsonConfig } from "./json-config.ts";
-
-// .env가 env.ts보다 먼저 로드되지 않는 경우를 위한 안전장치
-dotenv.config({ path: path.resolve(resolveConfigsDir(), "..", ".env") });
-
-const serverConfigSchema = z.object({
-    /** HTTP 리슨 포트 */
-    port: z.coerce.number().int().min(1).max(65535).default(3000),
-    /** 바인드 호스트 */
-    host: z.string().default("0.0.0.0"),
-    /** 공개 베이스 URL (예: https://api.yourdomain.com) */
-    baseUrl: z.string().optional(),
-    /**
-     * 인스턴스 네임스페이스 — 캐시 키 앞에 붙는 식별자.
-     * Redis/Memcached를 여러 앱이 공유할 때 키 충돌을 방지합니다.
-     * 기본값: "gw"
-     */
-    namespace: z.string().default("gw"),
-    /** 로깅 설정 */
-    logging: z
-        .object({
-            /** pino 로그 레벨 */
-            level: z
-                .enum(["fatal", "error", "warn", "info", "debug", "trace"])
-                .default("info"),
-            /** 로그 파일 저장 경로 */
-            logDir: z.string().default("./logs"),
-            /** HTTP 접근 로그 */
-            access: z
-                .object({
-                    enabled: z.boolean().default(true),
-                    /** 파일 기본명 (예: access -> YYYY-MM-DD.access.log) */
-                    filename: z.string().default("access"),
-                    /** 로테이션 주기: 'daily' | 'hourly' */
-                    frequency: z.enum(["daily", "hourly"]).default("daily"),
-                    /** 보관할 최대 파일 수 (초과분 자동 삭제) */
-                    maxFiles: z.coerce.number().int().min(1).default(14),
-                    /** 파일당 최대 크기 (예: '100m', '1g') — 초과 시 즉시 로테이션 */
-                    maxSize: z.string().default("100m"),
-                })
-                .default({}),
-            /** 에러 로그 (error 레벨 이상만 별도 파일) */
-            error: z
-                .object({
-                    enabled: z.boolean().default(true),
-                    /** 파일 기본명 (예: error -> YYYY-MM-DD.error.log) */
-                    filename: z.string().default("error"),
-                    frequency: z.enum(["daily", "hourly"]).default("daily"),
-                    maxFiles: z.coerce.number().int().min(1).default(30),
-                    maxSize: z.string().default("50m"),
-                })
-                .default({}),
-            /** 앱 일반 로그 (설정된 level 이상 전체) */
-            app: z
-                .object({
-                    enabled: z.boolean().default(true),
-                    /** 파일 기본명 (예: app -> YYYY-MM-DD.app.log) */
-                    filename: z.string().default("app"),
-                    frequency: z.enum(["daily", "hourly"]).default("daily"),
-                    maxFiles: z.coerce.number().int().min(1).default(14),
-                    maxSize: z.string().default("100m"),
-                })
-                .default({}),
-        })
-        .default({}),
-});
-
-export type ServerConfig = z.infer<typeof serverConfigSchema>;
-
-/** 서버 설정 파일(server.json)을 로드하고 파싱한다 */
-export function loadServerConfig(): ServerConfig {
-    const raw = loadJsonConfig<Record<string, unknown>>("server.json");
-    return serverConfigSchema.parse(raw ?? {});
-}
-
-export const serverConfig = loadServerConfig();

package/src/system/crypto/cipher.ts

@@ -1,117 +0,0 @@
-/**
- * 범용 암호화 유틸리티 — AES-CBC, 3DES-CBC, HMAC-SHA256
- *
- * 본인인증(identity) 등 여러 확장모듈에서 재사용한다.
- */
-
-import {
-    createCipheriv,
-    createDecipheriv,
-    createHmac,
-    createHash,
-} from "node:crypto";
-
-// ── PKCS7 패딩 ──
-
-/** PKCS#7 패딩을 적용한다 */
-function pkcs7Pad(data: Buffer, blockSize: number): Buffer {
-    const padding = blockSize - (data.length % blockSize);
-    const padBuf = Buffer.alloc(padding, padding);
-    return Buffer.concat([data, padBuf]);
-}
-
-/** PKCS#7 패딩을 제거한다 */
-function pkcs7Unpad(data: Buffer): Buffer {
-    if (data.length === 0) throw new Error("crypto: empty data");
-    const padding = data[data.length - 1];
-    if (padding === 0 || padding > data.length) {
-        throw new Error("crypto: invalid padding");
-    }
-    for (let i = data.length - padding; i < data.length; i++) {
-        if (data[i] !== padding) {
-            throw new Error("crypto: invalid padding byte");
-        }
-    }
-    return data.subarray(0, data.length - padding);
-}
-
-// ── AES-CBC 암복호화 ──
-
-/** AES-CBC 모드로 데이터를 암호화한다 (Base64 반환) */
-export function encryptAesCbc(
-    plaintext: Buffer,
-    key: Buffer,
-    iv: Buffer,
-): string {
-    const algo = key.length === 16 ? "aes-128-cbc" : "aes-256-cbc";
-    const padded = pkcs7Pad(plaintext, 16);
-    const cipher = createCipheriv(algo, key, iv);
-    cipher.setAutoPadding(false);
-    const ct = Buffer.concat([cipher.update(padded), cipher.final()]);
-    return ct.toString("base64");
-}
-
-/** AES-CBC 모드로 데이터를 복호화한다 */
-export function decryptAesCbc(
-    ciphertext: string,
-    key: Buffer,
-    iv: Buffer,
-): Buffer {
-    const ct = Buffer.from(ciphertext, "base64");
-    const algo = key.length === 16 ? "aes-128-cbc" : "aes-256-cbc";
-    if (ct.length % 16 !== 0) {
-        throw new Error("crypto: ciphertext not aligned to block size");
-    }
-    const decipher = createDecipheriv(algo, key, iv);
-    decipher.setAutoPadding(false);
-    const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
-    return pkcs7Unpad(pt);
-}
-
-// ── 3DES-CBC 암복호화 ──
-
-/** 3DES-CBC 모드로 데이터를 암호화한다 (Base64 반환) */
-export function encrypt3DesCbc(
-    plaintext: Buffer,
-    key: Buffer,
-    iv: Buffer,
-): string {
-    const padded = pkcs7Pad(plaintext, 8);
-    const cipher = createCipheriv("des-ede3-cbc", key, iv);
-    cipher.setAutoPadding(false);
-    const ct = Buffer.concat([cipher.update(padded), cipher.final()]);
-    return ct.toString("base64");
-}
-
-/** 3DES-CBC 모드로 데이터를 복호화한다 */
-export function decrypt3DesCbc(
-    ciphertext: string,
-    key: Buffer,
-    iv: Buffer,
-): Buffer {
-    const ct = Buffer.from(ciphertext, "base64");
-    if (ct.length % 8 !== 0) {
-        throw new Error("crypto: ciphertext not aligned to block size");
-    }
-    const decipher = createDecipheriv("des-ede3-cbc", key, iv);
-    decipher.setAutoPadding(false);
-    const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
-    return pkcs7Unpad(pt);
-}
-
-// ── HMAC / Hash ──
-
-/** HMAC-SHA256 값을 Base64로 반환한다 */
-export function hmacSha256(data: Buffer, key: Buffer): string {
-    return createHmac("sha256", key).update(data).digest("base64");
-}
-
-/** SHA-256 해시를 hex 문자열로 반환한다 */
-export function sha256Hex(data: string): string {
-    return createHash("sha256").update(data).digest("hex");
-}
-
-/** SHA-256 해시를 Buffer로 반환한다 */
-export function sha256(data: string): Buffer {
-    return createHash("sha256").update(data).digest();
-}

package/src/system/crypto/data-encrypt.ts

@@ -1,174 +0,0 @@
-/**
- * DB 데이터 암/복호화 — XChaCha20-Poly1305 + AES-256-GCM fallback
- *
- * Go Entity Server의 EncryptData / DecryptData를 TypeScript로 포팅.
- * DB 암호화 포맷: base64([magic:"002":3][nonce:24][ciphertext+tag])
- * - 키 파생: HKDF(encryption_key, info="entity-server:db-encryption")
- */
-
-import { randomBytes } from "crypto";
-import { createRequire } from "module";
-import { deriveKey32HKDF } from "./packet.ts";
-
-const XCHACHA_NONCE_SIZE = 24;
-const POLY1305_TAG_SIZE = 16;
-const AES_GCM_NONCE_SIZE = 12;
-const AES_GCM_TAG_SIZE = 16;
-
-const DB_MAGIC_V2 = "002";
-const DB_MAGIC_SIZE = 3;
-
-// ─── libsodium 싱글턴 캐시 ────────────────────────────────────────────────
-
-type SodiumType = typeof import("libsodium-wrappers");
-let _sodiumPromise: Promise<SodiumType | null> | null = null;
-const require = createRequire(import.meta.url);
-
-async function getSodium(): Promise<SodiumType | null> {
-    if (!_sodiumPromise) {
-        _sodiumPromise = import("libsodium-wrappers")
-            .then(async (mod) => {
-                await mod.ready;
-                return mod;
-            })
-            .catch(async () => {
-                const mod = require("libsodium-wrappers") as SodiumType;
-                await mod.ready;
-                return mod;
-            })
-            .catch(() => {
-                _sodiumPromise = null;
-                return null;
-            });
-    }
-    return _sodiumPromise;
-}
-
-/**
- * DB 저장용 암호화 — base64([magic:"002":3][nonce:24][ciphertext+tag])
- * Go의 EncryptData와 동일
- */
-export async function encryptData(
-    data: Record<string, unknown>,
-    key: string,
-): Promise<string> {
-    const jsonData = Buffer.from(JSON.stringify(data));
-    const derivedKey = await deriveKey32HKDF(
-        key,
-        "entity-server:db-encryption",
-    );
-
-    try {
-        const sodium = await getSodium();
-        if (!sodium) throw new Error("libsodium not available");
-
-        const nonce = randomBytes(XCHACHA_NONCE_SIZE);
-        const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
-            jsonData,
-            null,
-            null,
-            nonce,
-            derivedKey,
-        );
-
-        const result = Buffer.concat([
-            Buffer.from(DB_MAGIC_V2),
-            nonce,
-            Buffer.from(ciphertext),
-        ]);
-        return result.toString("base64");
-    } catch {
-        // AES-256-GCM fallback
-        const { createCipheriv } = await import("crypto");
-        const nonce = randomBytes(AES_GCM_NONCE_SIZE);
-        const cipher = createCipheriv("aes-256-gcm", derivedKey, nonce);
-        const encrypted = Buffer.concat([
-            cipher.update(jsonData),
-            cipher.final(),
-        ]);
-        const tag = cipher.getAuthTag();
-
-        const result = Buffer.concat([
-            Buffer.from(DB_MAGIC_V2),
-            nonce,
-            tag,
-            encrypted,
-        ]);
-        return result.toString("base64");
-    }
-}
-
-/**
- * DB 문자열 복호화
- * Go의 DecryptData와 동일
- */
-export async function decryptData(
-    encoded: string,
-    key: string,
-): Promise<Record<string, unknown>> {
-    let raw: Buffer;
-    try {
-        raw = Buffer.from(encoded, "base64");
-    } catch {
-        return JSON.parse(encoded) as Record<string, unknown>;
-    }
-
-    const minLen = DB_MAGIC_SIZE + XCHACHA_NONCE_SIZE + POLY1305_TAG_SIZE;
-    if (
-        raw.length < minLen ||
-        raw.subarray(0, DB_MAGIC_SIZE).toString() !== DB_MAGIC_V2
-    ) {
-        return JSON.parse(encoded) as Record<string, unknown>;
-    }
-
-    const derivedKey = await deriveKey32HKDF(
-        key,
-        "entity-server:db-encryption",
-    );
-
-    try {
-        const sodium = await getSodium();
-        if (!sodium) throw new Error("libsodium not available");
-
-        const nonce = raw.subarray(
-            DB_MAGIC_SIZE,
-            DB_MAGIC_SIZE + XCHACHA_NONCE_SIZE,
-        );
-        const ciphertext = raw.subarray(DB_MAGIC_SIZE + XCHACHA_NONCE_SIZE);
-
-        const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(
-            null,
-            ciphertext,
-            null,
-            nonce,
-            derivedKey,
-        );
-
-        return JSON.parse(Buffer.from(plaintext).toString()) as Record<
-            string,
-            unknown
-        >;
-    } catch {
-        // AES-256-GCM fallback
-        const { createDecipheriv } = await import("crypto");
-        const nonce = raw.subarray(
-            DB_MAGIC_SIZE,
-            DB_MAGIC_SIZE + AES_GCM_NONCE_SIZE,
-        );
-        const tag = raw.subarray(
-            DB_MAGIC_SIZE + AES_GCM_NONCE_SIZE,
-            DB_MAGIC_SIZE + AES_GCM_NONCE_SIZE + AES_GCM_TAG_SIZE,
-        );
-        const ciphertext = raw.subarray(
-            DB_MAGIC_SIZE + AES_GCM_NONCE_SIZE + AES_GCM_TAG_SIZE,
-        );
-
-        const decipher = createDecipheriv("aes-256-gcm", derivedKey, nonce);
-        decipher.setAuthTag(tag);
-        const plaintext = Buffer.concat([
-            decipher.update(ciphertext),
-            decipher.final(),
-        ]);
-        return JSON.parse(plaintext.toString()) as Record<string, unknown>;
-    }
-}

package/src/system/crypto/hash.ts

@@ -1,24 +0,0 @@
-/**
- * SHA-256 해시 유틸리티
- *
- * 여러 플러그인(sms/verification, identity, ocr/cache, password-reset 등)에서
- * 반복되는 해시 로직을 통합한다.
- *
- * 참고: AES/3DES/HMAC 등 암복호화는 crypto/cipher.ts 를 사용한다.
- */
-
-import { createHash } from "node:crypto";
-
-/**
- * 문자열을 SHA-256 hex로 해시한다.
- */
-export function hashString(data: string): string {
-    return createHash("sha256").update(data, "utf-8").digest("hex");
-}
-
-/**
- * Buffer를 SHA-256 hex로 해시한다 (파일 해시 등).
- */
-export function hashBuffer(data: Buffer): string {
-    return createHash("sha256").update(data).digest("hex");
-}

package/src/system/crypto/packet.test.ts

@@ -1,23 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-    derivePacketKey,
-    packetMagicLenFromKey,
-    encryptPacket,
-    decryptPacket,
-} from "./packet.ts";
-
-describe("app-server packet wrapper", () => {
-    it("roundtrips through shared packet core", async () => {
-        const key = await derivePacketKey("packet-test-token");
-        const magicLen = packetMagicLenFromKey(key);
-        const plaintext = Buffer.from(JSON.stringify({ ok: true, via: "wrapper" }));
-
-        const encrypted = await encryptPacket(plaintext, key, magicLen);
-        const decrypted = await decryptPacket(encrypted, key, magicLen);
-
-        expect(decrypted.toString()).toBe(
-            JSON.stringify({ ok: true, via: "wrapper" }),
-        );
-    });
-});

package/src/system/crypto/packet.ts

@@ -1,97 +0,0 @@
-/**
- * 패킷 암호화 유틸리티 — XChaCha20-Poly1305
- *
- * Go Entity Server의 internal/crypto/packet.go를 TypeScript로 포팅.
- * 패킷 포맷: [random_magic:magicLen][random_nonce:24][ciphertext+tag]
- *
- * 키 파생: HKDF-SHA256
- * - JWT 인증:  HKDF(jwt_token,  info="entity-server:packet-encryption")
- * - HMAC 인증: HKDF(hmac_secret, info="entity-server:packet-encryption")
- */
-
-import { hkdf } from "crypto";
-import {
-    derivePacketKey as deriveSharedPacketKey,
-    packetMagicLenFromKey as derivePacketMagicLen,
-    encryptPacket as encryptSharedPacket,
-    decryptPacket as decryptSharedPacket,
-} from "entity-server-client/packet";
-
-const KEY_SIZE = 32;
-
-// magic 길이 파생 상수 (Go와 동일)
-export const PACKET_MAGIC_MIN = 2;
-export const PACKET_MAGIC_RANGE = 14;
-
-// HKDF salt (Go crypto/keys.go와 동일)
-const HKDF_SALT = "entity-server:hkdf:v1";
-
-/**
- * HKDF-SHA256으로 32바이트 키 유도
- * Go의 DeriveKey32HKDF와 동일
- */
-export function deriveKey32HKDF(source: string, info: string): Promise<Buffer> {
-    return new Promise((resolve, reject) => {
-        hkdf("sha256", source, HKDF_SALT, info, KEY_SIZE, (err, derivedKey) => {
-            if (err) return reject(err);
-            resolve(Buffer.from(derivedKey));
-        });
-    });
-}
-
-/**
- * JWT access token에서 패킷 키 유도
- * Go의 DerivePacketKey와 동일
- * @param infoLabel HKDF info 문자열 — security.json의 packet_encrypt.info_label과 일치해야 함
- */
-export function derivePacketKey(
-    accessToken: string,
-    infoLabel = "entity-server:packet-encryption",
-): Promise<Buffer> {
-    return Promise.resolve(
-        Buffer.from(deriveSharedPacketKey(accessToken, infoLabel)),
-    );
-}
-
-/**
- * 32바이트 키의 마지막 바이트에서 magic 길이 파생
- * Go의 PacketMagicLenFromKey와 동일
- */
-export function packetMagicLenFromKey(
-    key: Buffer,
-    magicMin = PACKET_MAGIC_MIN,
-    magicRange = PACKET_MAGIC_RANGE,
-): number {
-    return derivePacketMagicLen(key, magicMin, magicRange);
-}
-
-/**
- * XChaCha20-Poly1305 패킷 암호화
- * 포맷: [random_magic:magicLen][random_nonce:24][ciphertext+tag]
- */
-export async function encryptPacket(
-    plaintext: Buffer,
-    key: Buffer,
-    magicLen: number,
-): Promise<Buffer> {
-    const actualMagicMin = magicLen;
-    const actualMagicRange = 1;
-    return Buffer.from(
-        encryptSharedPacket(plaintext, key, actualMagicMin, actualMagicRange),
-    );
-}
-
-/**
- * XChaCha20-Poly1305 패킷 복호화
- */
-export async function decryptPacket(
-    data: Buffer,
-    key: Buffer,
-    magicLen: number,
-): Promise<Buffer> {
-    const actualMagicMin = magicLen;
-    const actualMagicRange = 1;
-    return Buffer.from(
-        decryptSharedPacket(data, key, actualMagicMin, actualMagicRange),
-    );
-}

package/src/system/crypto/random.ts

@@ -1,19 +0,0 @@
-/**
- * 암호학적 난수 유틸리티 — 인증코드, 토큰 생성 등
- *
- * 참고: 해시 함수는 crypto/hash.ts, 암복호화는 crypto/cipher.ts 를 사용한다.
- */
-
-import { randomInt } from "node:crypto";
-
-/**
- * 숫자 인증 코드를 생성한다.
- *
- * @param length 코드 자릿수 (기본 6)
- * @returns 지정 자릿수의 숫자 문자열 (예: "183927")
- */
-export function generateVerificationCode(length = 6): string {
-    const min = Math.pow(10, length - 1);
-    const max = Math.pow(10, length);
-    return String(randomInt(min, max));
-}

package/src/system/email/sender.ts

@@ -1,85 +0,0 @@
-/**
- * SMTP 발송 유틸리티
- *
- * 게이트웨이에서 엔티티서버 SMTP API (/v1/smtp/send)를 경유하여 이메일을 발송한다.
- * 로컬 템플릿 렌더링 후 body_html을 전달하거나,
- * 엔티티서버 측 템플릿을 사용할 수도 있다.
- */
-
-import { entityServer, logger } from "@gateway/api";
-import { renderTemplate } from "./template-engine.ts";
-
-export interface SendEmailParams {
-    /** 수신자 이메일 (1개 이상 필수) */
-    to: string[];
-    /** 제목 */
-    subject: string;
-    /** 게이트웨이 로컬 템플릿명 (확장자 제외) */
-    templateName?: string;
-    /** 템플릿 파일이 위치한 절대경로 디렉토리 (미지정 시 전역 setTemplateDir 사용) */
-    templateDir?: string;
-    /** 템플릿 변수 */
-    templateData?: Record<string, unknown>;
-    /** 직접 HTML 본문 (templateName 대신 사용) */
-    bodyHtml?: string;
-    /** 텍스트 본문 */
-    bodyText?: string;
-    /** CC */
-    cc?: string[];
-    /** BCC */
-    bcc?: string[];
-    /** 발신자 */
-    from?: string;
-    /** Reply-To */
-    replyTo?: string;
-    /** 참조 엔티티 */
-    refEntity?: string;
-    /** 참조 seq */
-    refSeq?: number;
-}
-
-/**
- * 이메일을 발송한다.
- *
- * templateName이 지정되면 게이트웨이 로컬 템플릿을 렌더링하여 body_html로 전달.
- * bodyHtml이 직접 지정되면 그대로 전달.
- *
- * @returns 발송 큐 등록 seq
- */
-export async function sendEmail(params: SendEmailParams): Promise<number> {
-    let html = params.bodyHtml ?? "";
-
-    // 로컬 템플릿 렌더링
-    if (params.templateName) {
-        const rendered = renderTemplate(
-            params.templateName,
-            params.templateData ?? {},
-            params.templateDir,
-        );
-        if (!rendered) {
-            logger.error(
-                { template: params.templateName },
-                "Email template rendering failed",
-            );
-            throw new Error(
-                `Email template not found: ${params.templateName}`,
-            );
-        }
-        html = rendered;
-    }
-
-    const resp = await entityServer.smtpSend({
-        to: params.to,
-        subject: params.subject,
-        body_html: html || undefined,
-        body_text: params.bodyText,
-        cc: params.cc,
-        bcc: params.bcc,
-        from: params.from,
-        reply_to: params.replyTo,
-        ref_entity: params.refEntity,
-        ref_seq: params.refSeq,
-    });
-
-    return resp.seq ?? 0;
-}