create-entity-app-server 0.0.3

package/src/app/plugins/sms/providers/solapi.ts

@@ -0,0 +1,83 @@
+/**
+ * Solapi(CoolSMS) SMS 프로바이더
+ *
+ * Go 엔티티서버 `internal/sms/client_solapi.go`에서 포팅
+ *
+ * 인증: HMAC-SHA256
+ *   Authorization: HMAC-SHA256 apiKey={key}, date={ISO8601}, salt={random}, signature={hmac(date+salt)}
+ * URL: POST https://api.solapi.com/messages/v4/send
+ * Content-Type: application/json
+ */
+
+import { buildSolapiAuthorization } from "../../providers/solapi-auth.ts";
+import type {
+    SmsClient,
+    SendRequest,
+    SendResult,
+    SmsProviderConfig,
+} from "../types/index.ts";
+
+const SOLAPI_API_URL = "https://api.solapi.com/messages/v4/send";
+const TIMEOUT_MS = 30_000;
+
+export class SolapiClient implements SmsClient {
+    private readonly apiKey: string;
+    private readonly apiSecret: string;
+
+    constructor(cfg: SmsProviderConfig) {
+        this.apiKey = cfg.api_key ?? "";
+        this.apiSecret = cfg.api_secret ?? "";
+    }
+
+    name(): string {
+        return "solapi";
+    }
+
+    async send(req: SendRequest): Promise<SendResult> {
+        const { authorization } = buildSolapiAuthorization(
+            this.apiKey,
+            this.apiSecret,
+        );
+
+        const body: Record<string, unknown> = {
+            message: {
+                to: req.receiver,
+                from: req.sender,
+                text: req.content,
+                type: req.type.toUpperCase(),
+                ...(req.subject ? { subject: req.subject } : {}),
+                ...(req.image_url ? { imageUrl: req.image_url } : {}),
+            },
+        };
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+        try {
+            const response = await fetch(SOLAPI_API_URL, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: authorization,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(
+                    `Solapi error: status=${response.status}, body=${text}`,
+                );
+            }
+
+            const result = (await response.json()) as { groupId?: string };
+            return {
+                provider_msg_id: result.groupId ?? "",
+                status_code: String(response.status),
+            };
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+}

package/src/app/plugins/sms/routes.ts

@@ -0,0 +1,23 @@
+/**
+ * SMS 라우트 테이블
+ * 등록 경로: /api/v1/sms/*
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+/** SMS 라우트를 등록한다 */
+export default async function smsRoutes(app: FastifyInstance) {
+    // POST /api/v1/sms/send — SMS/LMS/MMS 발송 큐 등록
+    app.post("/send", h.handleSend);
+
+    // GET /api/v1/sms/status/:seq — 발송 상태 조회
+    app.get("/status/:seq", h.handleStatus);
+
+    // 인증번호 라우트 (인증 불필요)
+    // POST /api/v1/sms/verification/send — 인증번호 발송
+    app.post("/verification/send", h.handleVerificationSend);
+
+    // POST /api/v1/sms/verification/verify — 인증번호 검증
+    app.post("/verification/verify", h.handleVerificationVerify);
+}

package/src/app/plugins/sms/service.ts

@@ -0,0 +1,239 @@
+/**
+ * SMS 발송 서비스
+ *
+ * Go 엔티티서버 `internal/sms/service.go`에서 포팅
+ *
+ * 흐름:
+ *  1. enqueueJob() → sms_log(pending) DB 저장
+ *  2. dispatchLoop (setInterval N초) → pending 조회 → processing으로 claim → processOne 호출
+ *  3. processOne → 프로바이더 API 발송 → sms_log 상태 갱신 (sent/failed)
+ *  4. 서버 시작 시 → resetStaleLogs → processing → pending 되돌림
+ */
+
+import { logger } from "@gateway/api";
+import type {
+    SmsConfig,
+    SmsClient,
+    SmsQuerier,
+    SmsJob,
+    PendingSmsLog,
+    SendRequest,
+} from "./types/index.ts";
+import { determineMsgType } from "./providers/index.ts";
+
+export class SmsService {
+    private readonly config: SmsConfig;
+    private readonly clients: Map<string, SmsClient>;
+
+    private querier: SmsQuerier | null = null;
+    private dispatchTimer: ReturnType<typeof setInterval> | null = null;
+    private running = false;
+    private activeWorkers = 0;
+    private activeDispatch: Promise<void> | null = null;
+
+    constructor(config: SmsConfig, clients: Map<string, SmsClient>) {
+        this.config = config;
+        this.clients = clients;
+    }
+
+    setQuerier(q: SmsQuerier): void {
+        this.querier = q;
+    }
+
+    getConfig(): SmsConfig {
+        return this.config;
+    }
+
+    /** 서비스를 시작한다 (stale 복구 + dispatch loop) */
+    async start(): Promise<void> {
+        if (!this.querier) {
+            logger.warn("SMS: querier not set, service will not start");
+            return;
+        }
+
+        // stale processing 로그 복구
+        try {
+            await this.querier.resetStaleSmsLogs();
+        } catch (err) {
+            logger.warn({ err }, "SMS: failed to reset stale logs");
+        }
+
+        this.running = true;
+
+        const intervalMs = (this.config.dispatch_interval_sec || 5) * 1000;
+        this.dispatchTimer = setInterval(() => {
+            const p = this.dispatch().catch((err) =>
+                logger.error({ err }, "SMS dispatch error"),
+            );
+            this.activeDispatch = p;
+        }, intervalMs);
+
+        logger.info(
+            `SMS service started (workers=${this.config.workers}, interval=${this.config.dispatch_interval_sec}s)`,
+        );
+    }
+
+    /** 서비스를 중지한다 (진행 중인 발송 완료 대기) */
+    async stop(): Promise<void> {
+        this.running = false;
+        if (this.dispatchTimer) {
+            clearInterval(this.dispatchTimer);
+            this.dispatchTimer = null;
+        }
+        // 진행 중인 dispatch 완료 대기
+        if (this.activeDispatch) {
+            try {
+                await this.activeDispatch;
+            } catch {
+                // best-effort
+            }
+        }
+        logger.info("SMS service stopped");
+    }
+
+    /** SMS 발송 작업을 큐에 등록한다 */
+    async enqueueJob(job: SmsJob): Promise<void> {
+        if (!this.querier) {
+            throw new Error("SMS service not initialized");
+        }
+
+        // provider 기본값
+        const provider = job.provider || this.config.default;
+        // sender 기본값
+        const sender =
+            job.sender ||
+            this.findProviderSender(provider) ||
+            this.config.sender;
+
+        // 메시지 타입 자동 판정
+        let msgType = job.msg_type;
+        if (!msgType && this.config.auto_lms) {
+            msgType = determineMsgType(
+                job.content,
+                this.config.lms_threshold_bytes,
+                job.image_url,
+            );
+        }
+        if (!msgType) msgType = "sms";
+
+        await this.querier.submitSmsLog({
+            status: "pending",
+            provider,
+            sender,
+            receiver: job.receiver,
+            content: job.content,
+            subject: job.subject || "",
+            msg_type: msgType,
+            image_url: job.image_url || "",
+            ref_entity: job.ref_entity || "",
+            ref_seq: job.ref_seq || 0,
+            sms_msg_seq: job.sms_msg_seq || 0,
+            retry_count: 0,
+            error_message: "",
+        });
+    }
+
+    /** pending 로그를 가져와 발송한다 */
+    private async dispatch(): Promise<void> {
+        if (!this.running || !this.querier) return;
+
+        const logs = await this.querier.claimPendingSmsLogs(
+            this.config.queue_size,
+        );
+        if (logs.length === 0) return;
+
+        // 동시 발송 (workers 만큼 제한)
+        const maxConcurrency = this.config.workers || 2;
+        const queue = [...logs];
+
+        const processNext = async (): Promise<void> => {
+            while (queue.length > 0 && this.running) {
+                const pending = queue.shift();
+                if (!pending) break;
+                await this.processOne(pending);
+            }
+        };
+
+        const workers = Array.from(
+            { length: Math.min(maxConcurrency, logs.length) },
+            () => processNext(),
+        );
+        await Promise.allSettled(workers);
+    }
+
+    /** 단일 SMS 로그를 발송 처리한다 */
+    private async processOne(pending: PendingSmsLog): Promise<void> {
+        const client = this.clients.get(pending.provider);
+        if (!client) {
+            await this.finalize(
+                pending,
+                "",
+                new Error(`Unknown provider: ${pending.provider}`),
+            );
+            return;
+        }
+
+        const req: SendRequest = {
+            type: pending.msg_type || "sms",
+            sender: pending.sender,
+            receiver: pending.receiver,
+            subject: pending.subject,
+            content: pending.content,
+            image_url: pending.image_url,
+        };
+
+        try {
+            const result = await client.send(req);
+            await this.finalize(pending, result.provider_msg_id, null);
+        } catch (err) {
+            await this.finalize(
+                pending,
+                "",
+                err instanceof Error ? err : new Error(String(err)),
+            );
+        }
+    }
+
+    /** 발송 결과에 따라 로그 상태를 갱신한다 */
+    private async finalize(
+        pending: PendingSmsLog,
+        providerMsgId: string,
+        sendErr: Error | null,
+    ): Promise<void> {
+        if (!this.querier) return;
+
+        if (sendErr) {
+            logger.warn(
+                { err: sendErr, seq: pending.log_seq },
+                `SMS send failed (provider=${pending.provider})`,
+            );
+            await this.querier.updateSmsLogStatus(
+                pending.log_seq,
+                "failed",
+                "",
+                sendErr.message,
+            );
+        } else {
+            await this.querier.updateSmsLogStatus(
+                pending.log_seq,
+                "sent",
+                providerMsgId,
+                "",
+            );
+        }
+
+        // sms_msg 참조가 있으면 상태 연동
+        if (pending.sms_msg_seq > 0) {
+            await this.querier.updateSmsMsgStatus(
+                pending.sms_msg_seq,
+                sendErr ? "failed" : "sent",
+            );
+        }
+    }
+
+    /** 프로바이더별 발신번호 오버라이드를 찾는다 */
+    private findProviderSender(name: string): string {
+        const prov = this.config.providers[name];
+        return prov?.sender ?? "";
+    }
+}

package/src/app/plugins/sms/types/client.ts

@@ -0,0 +1,41 @@
+/**
+ * SMS 클라이언트(프로바이더) 인터페이스 + Querier 인터페이스
+ *
+ * Go 엔티티서버 `internal/sms/client.go`, `internal/sms/entity_adapter.go`에서 포팅
+ */
+
+import type { SendRequest, SendResult, PendingSmsLog } from "./job.ts";
+
+/** SMS 프로바이더 클라이언트 인터페이스 */
+export interface SmsClient {
+    send(req: SendRequest): Promise<SendResult>;
+    name(): string;
+}
+
+/** SMS DB 큐 어댑터 인터페이스 */
+export interface SmsQuerier {
+    submitSmsLog(data: Record<string, unknown>): Promise<void>;
+    claimPendingSmsLogs(limit: number): Promise<PendingSmsLog[]>;
+    updateSmsLogStatus(
+        logSeq: number,
+        status: string,
+        providerMsgId: string,
+        errMsg: string,
+    ): Promise<void>;
+    resetStaleSmsLogs(): Promise<void>;
+    updateSmsMsgStatus(msgSeq: number, status: string): Promise<void>;
+}
+
+/** SMS 인증번호 DB 어댑터 인터페이스 */
+export interface VerificationQuerier {
+    submitVerification(data: Record<string, unknown>): Promise<number>;
+    findPendingVerification(
+        phone: string,
+        purpose: string,
+    ): Promise<Record<string, unknown> | null>;
+    updateVerification(
+        seq: number,
+        data: Record<string, unknown>,
+    ): Promise<void>;
+    expireOldVerifications(phone: string, purpose: string): Promise<void>;
+}

package/src/app/plugins/sms/types/config.ts

@@ -0,0 +1,46 @@
+/**
+ * SMS 설정 타입 정의
+ *
+ * Go 엔티티서버 `internal/types/sms_config.go`에서 포팅
+ */
+
+export interface SmsConfig {
+    enabled?: boolean;
+    default: string; // 기본 프로바이더 driver 이름
+    sender: string; // 글로벌 발신번호
+    workers: number; // 워커 수 (기본 2)
+    queue_size: number; // dispatch당 claim 수 (기본 200)
+    dispatch_interval_sec: number; // 디스패치 주기 초 (기본 5)
+    max_retries: number; // 최대 재시도 (기본 3)
+    auto_lms: boolean; // 자동 LMS 판정 (기본 true)
+    lms_threshold_bytes: number; // LMS 판정 바이트 임계값 (기본 80)
+    providers: Record<string, SmsProviderConfig>; // 프로바이더 목록 (키=provider name)
+    rate_limit?: SmsRateLimitConfig; // Rate limit
+    verification?: SmsVerificationConfig; // 인증번호 설정
+}
+
+export interface SmsProviderConfig {
+    driver: string;
+    api_key?: string;
+    api_secret?: string;
+    user_id?: string;
+    account?: string;
+    app_key?: string;
+    secret_key?: string;
+    region?: string;
+    access_key?: string;
+    sender?: string;
+}
+
+export interface SmsRateLimitConfig {
+    per_number_per_minute: number;
+    per_minute: number;
+    per_hour: number;
+}
+
+export interface SmsVerificationConfig {
+    code_length: number;
+    ttl_sec: number;
+    max_attempts: number;
+    cooldown_sec: number;
+}

package/src/app/plugins/sms/types/index.ts

@@ -0,0 +1,3 @@
+export * from "./config.ts";
+export * from "./job.ts";
+export * from "./client.ts";

package/src/app/plugins/sms/types/job.ts

@@ -0,0 +1,51 @@
+/**
+ * SMS Job / Log 타입 정의
+ *
+ * Go 엔티티서버 `internal/sms/types.go`에서 포팅
+ */
+
+export interface SmsJob {
+    /** 프로바이더 driver (빈 문자열이면 config.default 사용) */
+    provider: string;
+    receiver: string;
+    /** 발신번호 (빈 문자열이면 config.sender 사용) */
+    sender: string;
+    content: string;
+    /** LMS/MMS용 제목 */
+    subject: string;
+    /** "sms" | "lms" | "mms" (빈 값 → 자동 판정) */
+    msg_type: string;
+    /** MMS 이미지 URL */
+    image_url: string;
+    ref_entity: string;
+    ref_seq: number;
+    /** sms_msg 참조 시퀀스 */
+    sms_msg_seq: number;
+}
+
+export interface PendingSmsLog {
+    log_seq: number;
+    provider: string;
+    sender: string;
+    receiver: string;
+    content: string;
+    subject: string;
+    msg_type: string;
+    image_url: string;
+    retry_count: number;
+    sms_msg_seq: number;
+}
+
+export interface SendRequest {
+    type: string;
+    sender: string;
+    receiver: string;
+    subject: string;
+    content: string;
+    image_url: string;
+}
+
+export interface SendResult {
+    provider_msg_id: string;
+    status_code: string;
+}

package/src/app/plugins/sms/verification.ts

@@ -0,0 +1,162 @@
+/**
+ * SMS 인증번호 발송/검증 서비스
+ *
+ * Go 엔티티서버 `internal/sms/verification.go`에서 포팅
+ *
+ * 흐름:
+ *  1. SendVerificationCode: 이전 pending 만료 → 코드 생성 → SHA-256 해시 저장 → SMS 발송
+ *  2. VerifyCode: pending 조회 → 만료 확인 → 시도 횟수 확인 → constant-time 비교 → verified
+ */
+
+import { createHash, randomInt, timingSafeEqual } from "node:crypto";
+import { logger } from "@gateway/api";
+import type { SmsVerificationConfig, VerificationQuerier } from "./types/index.ts";
+import type { SmsService } from "./service.ts";
+
+export class VerificationService {
+    private readonly smsService: SmsService;
+    private readonly querier: VerificationQuerier;
+    private readonly codeLength: number;
+    private readonly ttlSec: number;
+    private readonly maxAttempts: number;
+    private readonly cooldownSec: number;
+
+    constructor(
+        smsService: SmsService,
+        querier: VerificationQuerier,
+        cfg?: SmsVerificationConfig,
+    ) {
+        this.smsService = smsService;
+        this.querier = querier;
+        this.codeLength = cfg?.code_length ?? 6;
+        this.ttlSec = cfg?.ttl_sec ?? 180;
+        this.maxAttempts = cfg?.max_attempts ?? 5;
+        this.cooldownSec = cfg?.cooldown_sec ?? 60;
+    }
+
+    /**
+     * 인증번호를 발송한다.
+     * @returns 만료까지 남은 초 (ttl_sec)
+     */
+    async sendVerificationCode(
+        phone: string,
+        purpose: string,
+    ): Promise<number> {
+        // 1. 이전 pending 건 만료
+        await this.querier.expireOldVerifications(phone, purpose);
+
+        // 2. 인증번호 생성
+        const code = generateVerificationCode(this.codeLength);
+        const codeHash = hashCode(code);
+
+        // 3. 만료 시각 계산
+        const expiresAt = new Date(
+            Date.now() + this.ttlSec * 1000,
+        ).toISOString();
+
+        // 4. DB 저장
+        await this.querier.submitVerification({
+            phone,
+            purpose,
+            status: "pending",
+            code_hash: codeHash,
+            expires_at: expiresAt,
+            attempts: 0,
+        });
+
+        // 5. SMS 발송
+        const minutes = Math.floor(this.ttlSec / 60);
+        const content = `[인증번호] ${code} (${minutes}분 유효)`;
+        await this.smsService.enqueueJob({
+            provider: "",
+            receiver: phone,
+            sender: "",
+            content,
+            subject: "",
+            msg_type: "sms",
+            image_url: "",
+            ref_entity: "sms_verification",
+            ref_seq: 0,
+            sms_msg_seq: 0,
+        });
+
+        logger.info({ phone, purpose }, "SMS verification code sent");
+        return this.ttlSec;
+    }
+
+    /**
+     * 인증번호를 검증한다.
+     * @returns 검증 결과 { verified, error? }
+     */
+    async verifyCode(
+        phone: string,
+        purpose: string,
+        code: string,
+    ): Promise<{ verified: boolean; error?: string }> {
+        // 1. pending 레코드 조회
+        const record = await this.querier.findPendingVerification(
+            phone,
+            purpose,
+        );
+        if (!record) return { verified: false, error: "no pending verification found" };
+
+        const seq = Number(record.seq ?? 0);
+        if (seq <= 0) return { verified: false, error: "no pending verification found" };
+
+        // 2. 만료 확인
+        const expiresAt = new Date(String(record.expires_at ?? ""));
+        if (expiresAt.getTime() < Date.now()) {
+            await this.querier.updateVerification(seq, {
+                status: "expired",
+            });
+            return { verified: false, error: "code expired" };
+        }
+
+        // 3. 시도 횟수 확인
+        const attempts = Number(record.attempts ?? 0);
+        if (attempts >= this.maxAttempts) {
+            await this.querier.updateVerification(seq, {
+                status: "expired",
+            });
+            return { verified: false, error: "max attempts exceeded" };
+        }
+
+        // 4. constant-time 비교
+        const inputHash = hashCode(code);
+        const storedHash = String(record.code_hash ?? "");
+
+        const inputBuf = Buffer.from(inputHash, "utf-8");
+        const storedBuf = Buffer.from(storedHash, "utf-8");
+
+        if (
+            inputBuf.length !== storedBuf.length ||
+            !timingSafeEqual(inputBuf, storedBuf)
+        ) {
+            // 불일치 시에만 시도 횟수 증가 (Go 동일 패턴)
+            await this.querier.updateVerification(seq, {
+                attempts: attempts + 1,
+            });
+            return { verified: false };
+        }
+
+        // 5. 성공 → verified
+        await this.querier.updateVerification(seq, {
+            status: "verified",
+        });
+
+        logger.info({ phone, purpose }, "SMS verification code verified");
+        return { verified: true };
+    }
+}
+
+/** crypto.randomInt 기반 N자리 숫자 인증번호 생성 */
+function generateVerificationCode(length: number): string {
+    const min = Math.pow(10, length - 1);
+    const max = Math.pow(10, length);
+    return String(randomInt(min, max));
+}
+
+/** SHA-256 해시 (hex) */
+function hashCode(code: string): string {
+    return createHash("sha256").update(code, "utf-8").digest("hex");
+}

package/src/app/plugins/smtp/config.json

@@ -0,0 +1,5 @@
+{
+    "enabled": true,
+    "deploy": true,
+    "minify": true
+}

package/src/app/plugins/smtp/config.ts

@@ -0,0 +1,41 @@
+/**
+ * SMTP 플러그인 설정 로더
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { SmtpPluginConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+/** SMTP 플러그인 설정을 로드한다 */
+export function loadSmtpConfig(): SmtpPluginConfig | null {
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+
+        // 환경변수 치환: ${VAR} → process.env.VAR
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_match, name) => process.env[name] ?? "",
+        );
+
+        const cfg: SmtpPluginConfig = JSON.parse(raw);
+
+        if (cfg.enabled === false) {
+            logger.info("SMTP plugin routes disabled in config");
+            return null;
+        }
+
+        return cfg;
+    } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            // config.json 없으면 기본값으로 활성화
+            return { enabled: true };
+        }
+        logger.error({ err }, "Failed to load SMTP config");
+        return null;
+    }
+}