create-entity-app-server 0.0.3

package/src/system/security/anonymous-device.ts

@@ -0,0 +1,98 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { entityServer, logger } from "@gateway/api";
+import { ensureAnonymousDeviceId } from "./anonymous-device-id.ts";
+import {
+    loadPacketEncryptConfig,
+    type PacketEncryptConfig,
+} from "../config/packet-encrypt.ts";
+import { postEntityAdmin } from "../entity-server/client.ts";
+import { formatSqlDateTime } from "../utils/format.ts";
+import { parseUserAgent } from "../utils/user-agent.ts";
+
+function buildAnonDevicePayload(req: FastifyRequest, deviceId: string) {
+    const now = formatSqlDateTime();
+    const userAgent = parseUserAgent(req.headers["user-agent"]);
+    const payload: Record<string, unknown> = {
+        id: deviceId,
+        last_seen_time: now,
+        last_ip_addr: req.ip,
+    };
+
+    if (userAgent.raw) {
+        payload.user_agent = userAgent.raw;
+        if (userAgent.platform) payload.platform = userAgent.platform;
+        if (userAgent.deviceType) payload.device_type = userAgent.deviceType;
+        if (userAgent.browser) payload.browser = userAgent.browser;
+        if (userAgent.browserVersion) {
+            payload.browser_version = userAgent.browserVersion;
+        }
+    }
+
+    return { now, payload };
+}
+
+async function ensureAnonDeviceSchema(): Promise<void> {
+    await postEntityAdmin("/anon_device/sync-schema");
+}
+
+async function upsertAnonymousDevice(
+    deviceId: string,
+    payload: Record<string, unknown>,
+    now: string,
+): Promise<void> {
+    const existing = await entityServer.list("anon_device", {
+        conditions: { id: deviceId },
+        page: 1,
+        limit: 1,
+    });
+
+    const item = ((existing.data as any)?.items ?? [])[0] as
+        | Record<string, unknown>
+        | undefined;
+
+    if (item?.seq) {
+        await entityServer.submit("anon_device", {
+            seq: Number(item.seq),
+            ...payload,
+        });
+        return;
+    }
+
+    await entityServer.submit("anon_device", {
+        ...payload,
+        first_seen_time: now,
+        calc_count: 0,
+    });
+}
+
+export async function ensureAndSyncAnonymousDevice(
+    req: FastifyRequest,
+    reply: FastifyReply,
+    cfg: PacketEncryptConfig = loadPacketEncryptConfig(),
+): Promise<string | null> {
+    const deviceId = ensureAnonymousDeviceId(req, reply, cfg);
+    if (!deviceId) return null;
+
+    const { now, payload } = buildAnonDevicePayload(req, deviceId);
+
+    try {
+        await upsertAnonymousDevice(deviceId, payload, now);
+    } catch (err) {
+        try {
+            await ensureAnonDeviceSchema();
+            await upsertAnonymousDevice(deviceId, payload, now);
+        } catch (retryErr) {
+            logger.warn(
+                {
+                    err: retryErr,
+                    cause: err,
+                    entity: "anon_device",
+                    deviceId,
+                },
+                "Anonymous device sync failed",
+            );
+        }
+    }
+
+    return deviceId;
+}

package/src/system/security/anonymous-packet-token.ts

@@ -0,0 +1,23 @@
+/**
+ * 익명 패킷 토큰 파생
+ *
+ * 디바이스 ID와 HMAC secret으로 패킷 암호화용 토큰을 생성합니다.
+ */
+
+import { createHmac } from "crypto";
+import { env } from "../config/env.ts";
+import type { PacketEncryptConfig } from "../config/packet-encrypt.ts";
+
+export function deriveAnonymousPacketToken(
+    deviceId: string,
+    cfgOrInfoLabel: PacketEncryptConfig | string,
+): string {
+    const infoLabel =
+        typeof cfgOrInfoLabel === "string"
+            ? cfgOrInfoLabel
+            : cfgOrInfoLabel.infoLabel;
+    const digest = createHmac("sha256", env.ENTITY_HMAC_SECRET)
+        .update(`${infoLabel}:anonymous:${deviceId}`)
+        .digest("base64url");
+    return `anon.v1.${digest}`;
+}

package/src/system/security/packet-bootstrap.ts

@@ -0,0 +1,16 @@
+/**
+ * packet-bootstrap — 호환 재내보내기
+ *
+ * 기존 import를 유지하기 위한 barrel. 실제 구현은 각 모듈로 분리됨.
+ */
+
+export {
+    loadPacketEncryptConfig,
+    type PacketEncryptConfig,
+} from "../config/packet-encrypt.ts";
+export { parseCookies, serializeCookie } from "../http/cookie.ts";
+export {
+    readAnonymousDeviceId,
+    ensureAnonymousDeviceId,
+} from "./anonymous-device-id.ts";
+export { deriveAnonymousPacketToken } from "./anonymous-packet-token.ts";

package/src/system/security/password-policy.ts

@@ -0,0 +1,191 @@
+/**
+ * 비밀번호 정책 검증
+ *
+ * configs/security.json 의 password_policy 섹션을 기반으로
+ * 회원가입·비밀번호 변경 시 복잡도/금지패턴을 검증한다.
+ *
+ * Go internal/privacy/service.go ValidatePasswordPolicy +
+ *    internal/security/password.go ValidateForbiddenPatterns 포팅
+ */
+
+import { z } from "zod";
+import { loadSecurityJson } from "../config/security-loader.ts";
+
+// ─── 스키마 ─────────────────────────────────────────────────────────────────
+
+const forbiddenPatternsSchema = z
+    .object({
+        sequential_digits: z.boolean().default(true),
+        repeated_chars: z.boolean().default(true),
+        keyboard_patterns: z.boolean().default(false),
+        sequential_length: z.coerce.number().int().min(2).default(4),
+    })
+    .default({});
+
+const piiCheckSchema = z
+    .object({
+        enabled: z.boolean().default(false),
+        entity: z.string().default("user"),
+        fields: z.array(z.string()).default([]),
+    })
+    .default({});
+
+const passwordPolicySchema = z.object({
+    enabled: z.boolean().default(false),
+    min_length: z.coerce.number().int().default(8),
+    max_length: z.coerce.number().int().default(128),
+    require_mixed_case: z.boolean().default(false),
+    require_number: z.boolean().default(false),
+    require_special: z.boolean().default(false),
+    history_count: z.coerce.number().int().default(5),
+    forbidden_patterns: forbiddenPatternsSchema,
+    pii_check: piiCheckSchema,
+});
+
+export type PasswordPolicy = z.infer<typeof passwordPolicySchema>;
+
+// ─── 로더 ───────────────────────────────────────────────────────────────────
+
+let _policy: PasswordPolicy | undefined;
+
+/** security.json 에서 password_policy 를 로드한다 (캐시) */
+export function loadPasswordPolicy(): PasswordPolicy {
+    if (_policy) return _policy;
+    const raw = loadSecurityJson();
+    _policy = passwordPolicySchema.parse(raw.password_policy ?? {});
+    return _policy;
+}
+
+// ─── 검증 ───────────────────────────────────────────────────────────────────
+
+/**
+ * 비밀번호가 정책에 부합하는지 검증한다.
+ *
+ * @param password 평문 비밀번호
+ * @param piiValues PII 필드값 배열 (예: ["01012345678", "19900101"])
+ *                  pii_check.enabled 시 비밀번호에 포함 여부를 검사한다.
+ * @returns null (통과) | 에러 메시지 문자열
+ */
+export function validatePassword(
+    password: string,
+    piiValues: string[] = [],
+): string | null {
+    const p = loadPasswordPolicy();
+    if (!p.enabled) return null;
+
+    // 길이
+    if (p.min_length > 0 && password.length < p.min_length) {
+        return `비밀번호는 최소 ${p.min_length}자 이상이어야 합니다`;
+    }
+    if (p.max_length > 0 && password.length > p.max_length) {
+        return `비밀번호는 ${p.max_length}자를 초과할 수 없습니다`;
+    }
+
+    // 대소문자 혼합
+    if (p.require_mixed_case) {
+        if (!/[A-Z]/.test(password) || !/[a-z]/.test(password)) {
+            return "비밀번호에 대소문자를 모두 포함해야 합니다";
+        }
+    }
+
+    // 숫자 포함
+    if (p.require_number) {
+        if (!/\d/.test(password)) {
+            return "비밀번호에 숫자가 포함되어야 합니다";
+        }
+    }
+
+    // 특수문자 포함
+    if (p.require_special) {
+        if (!/[^A-Za-z0-9]/.test(password)) {
+            return "비밀번호에 특수문자가 포함되어야 합니다";
+        }
+    }
+
+    // 금지 패턴
+    const fpErr = validateForbiddenPatterns(password, p.forbidden_patterns);
+    if (fpErr) return fpErr;
+
+    // PII 포함 검사
+    if (p.pii_check.enabled && piiValues.length > 0) {
+        const lower = password.toLowerCase();
+        for (const val of piiValues) {
+            const digits = val.replace(/\D/g, "");
+            if (digits.length >= 4 && lower.includes(digits)) {
+                return "비밀번호에 개인정보(전화번호, 생년월일 등)를 포함할 수 없습니다";
+            }
+            if (val.length >= 4 && lower.includes(val.toLowerCase())) {
+                return "비밀번호에 개인정보(전화번호, 생년월일 등)를 포함할 수 없습니다";
+            }
+        }
+    }
+
+    return null;
+}
+
+// ─── 금지 패턴 내부 함수 ─────────────────────────────────────────────────────
+
+function validateForbiddenPatterns(
+    password: string,
+    cfg: PasswordPolicy["forbidden_patterns"],
+): string | null {
+    const seqLen = cfg.sequential_length;
+
+    // 연속 숫자 (1234, 4321 등)
+    if (cfg.sequential_digits) {
+        for (let i = 0; i <= password.length - seqLen; i++) {
+            const sub = password.slice(i, i + seqLen);
+            if (
+                isSequentialDigits(sub, true) ||
+                isSequentialDigits(sub, false)
+            ) {
+                return `연속된 숫자(${seqLen}자 이상)는 사용할 수 없습니다`;
+            }
+        }
+    }
+
+    // 반복 문자 (aaaa, 1111 등)
+    if (cfg.repeated_chars) {
+        for (let i = 0; i <= password.length - seqLen; i++) {
+            let allSame = true;
+            for (let j = 1; j < seqLen; j++) {
+                if (password[i + j] !== password[i]) {
+                    allSame = false;
+                    break;
+                }
+            }
+            if (allSame) {
+                return `동일한 문자의 반복(${seqLen}자 이상)은 사용할 수 없습니다`;
+            }
+        }
+    }
+
+    // 키보드 패턴 (qwer, asdf 등)
+    if (cfg.keyboard_patterns) {
+        const rows = ["qwertyuiop", "asdfghjkl", "zxcvbnm", "1234567890"];
+        const lower = password.toLowerCase();
+        for (const row of rows) {
+            for (let s = 0; s <= row.length - seqLen; s++) {
+                const pattern = row.slice(s, s + seqLen);
+                const reversed = pattern.split("").reverse().join("");
+                if (lower.includes(pattern) || lower.includes(reversed)) {
+                    return `키보드 연속 문자(${seqLen}자 이상)는 사용할 수 없습니다`;
+                }
+            }
+        }
+    }
+
+    return null;
+}
+
+/** 숫자 문자열이 오름차(ascending) 또는 내림차인지 검사 */
+function isSequentialDigits(s: string, ascending: boolean): boolean {
+    for (const ch of s) {
+        if (ch < "0" || ch > "9") return false;
+    }
+    for (let i = 1; i < s.length; i++) {
+        const diff = s.charCodeAt(i) - s.charCodeAt(i - 1);
+        if (ascending ? diff !== 1 : diff !== -1) return false;
+    }
+    return true;
+}

package/src/system/startup-banner.ts

@@ -0,0 +1,191 @@
+import { env, isDev } from "./config/env.ts";
+import { serverConfig } from "./config/server.ts";
+import { loadCorsConfig } from "./config/cors.ts";
+import { loadSecurityJson } from "./config/security-loader.ts";
+import { loadDatabaseConfig } from "./config/database.ts";
+import { loadCacheConfig } from "./cache/config.ts";
+import { loadPasswordPolicy } from "./security/password-policy.ts";
+
+const ANSI = {
+    reset: "\u001b[0m",
+    cyan: "\u001b[96m",
+    green: "\u001b[92m",
+    pink: "\u001b[95m",
+    yellow: "\u001b[93m",
+} as const;
+
+const BANNER_WIDTH = 74;
+const BANNER_INNER_WIDTH = BANNER_WIDTH - 2;
+const BANNER_CONTENT_WIDTH = BANNER_INNER_WIDTH - 2;
+const ANSI_ESCAPE = /\u001b\[[0-9;]*m/g;
+
+export interface StartupSummary {
+    hookCount: number;
+    pluginCount: number;
+    routeCount: number;
+    scheduleCount: number;
+}
+
+function stripProtocol(text: string): string {
+    return text.replace(/^https?:\/\//, "");
+}
+
+function statusText(enabled: boolean): string {
+    return enabled ? color("enabled", ANSI.green) : "disabled";
+}
+
+function valueText(text: string): string {
+    return color(text, ANSI.pink);
+}
+
+function color(text: string, code: string): string {
+    return isDev ? `${code}${text}${ANSI.reset}` : text;
+}
+
+function visibleLength(text: string): number {
+    return text.replace(ANSI_ESCAPE, "").length;
+}
+
+function padRight(text: string, width: number): string {
+    const padding = Math.max(0, width - visibleLength(text));
+    return `${text}${" ".repeat(padding)}`;
+}
+
+function center(text: string, width: number): string {
+    const space = Math.max(0, width - visibleLength(text));
+    const left = Math.floor(space / 2);
+    const right = space - left;
+    return `${" ".repeat(left)}${text}${" ".repeat(right)}`;
+}
+
+function line(content = ""): string {
+    return `${color("│", ANSI.cyan)} ${padRight(content, BANNER_CONTENT_WIDTH)} ${color("│", ANSI.cyan)}`;
+}
+
+function kvPart(label: string, value: string, width: number): string {
+    if (!label && !value) {
+        return " ".repeat(width);
+    }
+
+    if (!label) {
+        return padRight(value, width);
+    }
+
+    const base = `${label} ${value}`;
+    const baseLength = visibleLength(base);
+    if (baseLength >= width) {
+        return padRight(base, width);
+    }
+
+    const dotCount = Math.max(
+        1,
+        width - visibleLength(label) - visibleLength(value) - 2,
+    );
+    return `${label} ${".".repeat(dotCount)} ${value}`;
+}
+
+function kv(
+    leftLabel: string,
+    leftValue: string,
+    rightLabel: string,
+    rightValue: string,
+): string {
+    const separator = "  ";
+    const leftWidth = Math.floor((BANNER_CONTENT_WIDTH - separator.length) / 2);
+    const rightWidth = BANNER_CONTENT_WIDTH - separator.length - leftWidth;
+    return `${kvPart(leftLabel, leftValue, leftWidth)}${separator}${kvPart(rightLabel, rightValue, rightWidth)}`;
+}
+
+export function printStartupBanner(
+    listenUrl: string,
+    summary: StartupSummary,
+): void {
+    const publicUrl = serverConfig.baseUrl?.trim() || "-";
+    const cacheConfig = loadCacheConfig();
+    const corsConfig = loadCorsConfig();
+    const databaseConfig = loadDatabaseConfig();
+    const securityConfig = loadSecurityJson();
+    const passwordPolicy = loadPasswordPolicy();
+    const name = `${color("Entity App Server", ANSI.green)} ${color("ready", ANSI.yellow)}`;
+    const listenText = stripProtocol(listenUrl);
+    const entityText = stripProtocol(env.ENTITY_SERVER_URL);
+    const publicText = publicUrl === "-" ? publicUrl : stripProtocol(publicUrl);
+    const showPublicUrl =
+        publicText !== "-" &&
+        publicText !== listenText &&
+        publicText !== `${serverConfig.host}:${serverConfig.port}`;
+    const csrfEnabled = securityConfig.csrf?.enabled === true;
+    const packetEncryptEnabled =
+        securityConfig.packet_encrypt?.enabled === true;
+    const defaultDbGroup = databaseConfig?.groups[databaseConfig.default];
+    const databaseText = defaultDbGroup ? databaseConfig.default : "disabled";
+    const lines = [
+        color(`┌${"─".repeat(BANNER_INNER_WIDTH)}┐`, ANSI.cyan),
+        line(center(name, BANNER_CONTENT_WIDTH)),
+        line(),
+        line(center(color(listenText, ANSI.yellow), BANNER_CONTENT_WIDTH)),
+        line(
+            center(
+                color(`Entity Server: ${entityText}`, ANSI.yellow),
+                BANNER_CONTENT_WIDTH,
+            ),
+        ),
+        line(center(color(env.NODE_ENV, ANSI.yellow), BANNER_CONTENT_WIDTH)),
+        line(),
+        line(
+            kv(
+                "Namespace",
+                valueText(serverConfig.namespace),
+                "Log Level",
+                valueText(serverConfig.logging.level),
+            ),
+        ),
+        ...(showPublicUrl
+            ? [line(kv("", "", "Public URL", valueText(publicText)))]
+            : []),
+        line(
+            kv(
+                "CORS",
+                statusText(corsConfig.enabled),
+                "CSRF",
+                statusText(csrfEnabled),
+            ),
+        ),
+        line(
+            kv(
+                "Packet Encrypt",
+                statusText(packetEncryptEnabled),
+                "Password Policy",
+                statusText(passwordPolicy.enabled),
+            ),
+        ),
+        line(
+            kv(
+                "Cache",
+                valueText(cacheConfig.driver),
+                "Database",
+                valueText(databaseText),
+            ),
+        ),
+        line(),
+        line(
+            kv(
+                "Hooks",
+                valueText(String(summary.hookCount)),
+                "Plugins",
+                valueText(String(summary.pluginCount)),
+            ),
+        ),
+        line(
+            kv(
+                "Routes",
+                valueText(String(summary.routeCount)),
+                "Schedules",
+                valueText(String(summary.scheduleCount)),
+            ),
+        ),
+        color(`└${"─".repeat(BANNER_INNER_WIDTH)}┘`, ANSI.cyan),
+    ];
+
+    process.stdout.write(`${lines.join("\n")}\n`);
+}

package/src/system/types/fastify.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Fastify 타입 확장 — req.user, app.db, app.authRequired 등
+ *
+ * system → app 역참조 제거: app 레이어 타입은 generic/unknown 으로 선언하고
+ * 실제 사용처에서 타입 단언(as)을 통해 구체 타입으로 변환한다.
+ */
+
+import type { Kysely } from "kysely";
+import type { UserInfo } from "../hooks/types.ts";
+import type { CacheStore } from "../cache/types.ts";
+
+declare module "fastify" {
+    interface FastifyRequest {
+        /** JWT 디코드된 사용자 정보 (프록시: decode만, 비즈니스: verify 후) */
+        user: UserInfo | null;
+        /** 패킷 복호화된 raw body (packet-encrypt 플러그인이 주입) */
+        rawBody?: Buffer;
+        /** 패킷 암호화 키 — 요청이 암호화된 경우 응답 암호화에 사용 */
+        _packetKey?: Buffer;
+    }
+
+    interface FastifyInstance {
+        /** Kysely DB 인스턴스 — default 그룹 (database.json 미설정 시 null) */
+        db: Kysely<any> | null;
+
+        /** 모든 DB 그룹 커넥션 맵 (database.json groups 키 → Kysely 인스턴스) */
+        dbGroups: Record<string, Kysely<any>>;
+
+        /** 비즈니스 라우트 preHandler: JWT verify + 만료 확인 */
+        authRequired: (
+            req: import("fastify").FastifyRequest,
+            reply: import("fastify").FastifyReply,
+        ) => Promise<void>;
+
+        /** OCR 서비스 인스턴스 (disabled 시 null) — app.plugins.ocr 에서 등록 */
+        ocrService: unknown;
+
+        /** 본인인증 서비스 인스턴스 (disabled 시 null) — app.plugins.identity 에서 등록 */
+        identityService: unknown;
+
+        /** 공통 캐시 스토어 (driver: memory | redis, configs/cache.json 참고) */
+        cache: CacheStore;
+
+        /** 한국 선박 입항 서비스 인스턴스 (disabled 시 null) — app.plugins.vessel_kr 에서 등록 */
+        vesselKrService: unknown;
+
+        /** 코베코 운임지수 서비스 인스턴스 (disabled 시 null) — app.plugins.kobc_freight 에서 등록 */
+        kobcFreightService: unknown;
+
+        /** AIS 선박 위치 서비스 인스턴스 (disabled 시 null) — app.plugins.ais 에서 등록 */
+        aisService: unknown;
+    }
+}

package/src/system/utils/app-path.ts

@@ -0,0 +1,31 @@
+/**
+ * app 디렉토리 경로 헬퍼
+ *
+ * system.js가 번들된 환경(prod)과 tsx로 직접 실행하는 환경(dev) 양쪽에서
+ * app/ 디렉토리를 올바르게 찾아준다.
+ *
+ * 경로 기준:
+ *   prod: dist/system.js  → import.meta.url 기준 base = dist/  → dist/app/ 존재
+ *   dev:  src/system/**   → import.meta.url 기준 base = src/system/[subdir]/
+ *                          → 2단계 상위(src/) + app = src/app/
+ */
+
+import path from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+
+/**
+ * 호출 측의 import.meta.url을 전달하면 app/ 루트 절대경로를 반환한다.
+ *
+ * @param callerMetaUrl - 호출 파일의 import.meta.url
+ */
+export function resolveAppRoot(callerMetaUrl: string): string {
+    const base = path.dirname(fileURLToPath(callerMetaUrl));
+
+    // prod: system.js (dist/) 기준 → dist/app 이 존재
+    const prodApp = path.join(base, "app");
+    if (existsSync(prodApp)) return prodApp;
+
+    // dev: src/system/[plugins|routes|hooks]/ 기준 → ../../app = src/app
+    return path.resolve(base, "..", "..", "app");
+}

package/src/system/utils/coerce.ts

@@ -0,0 +1,28 @@
+/**
+ * 안전한 타입 변환 헬퍼
+ *
+ * unknown 값을 number, string 등으로 안전하게 변환한다.
+ * pg, taxinvoice 등 여러 플러그인의 entity-adapter 에서 공통으로 사용.
+ */
+
+/** unknown → number (null/NaN → 0) */
+export function toNumber(v: unknown): number {
+    if (v == null) return 0;
+    const n = Number(v);
+    return Number.isNaN(n) ? 0 : n;
+}
+
+/** unknown → string (null → "") */
+export function toString(v: unknown): string {
+    if (v == null) return "";
+    return String(v);
+}
+
+/** unknown → boolean (truthy 변환) */
+export function toBool(v: unknown): boolean {
+    if (v == null) return false;
+    if (typeof v === "string") {
+        return v === "true" || v === "1" || v === "yes";
+    }
+    return Boolean(v);
+}