create-entity-app-server 0.0.3

package/src/app/plugins/2fa/index.ts

@@ -0,0 +1,50 @@
+/**
+ * 2FA (TOTP) 플러그인
+ *
+ * config.json enabled: true 이면 account 엔티티에 totp_* 필드를 additive-sync 한 뒤
+ * /api/v1/account/2fa/* 라우트를 등록한다.
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+    ensurePluginEntities,
+    registerWithdrawHook,
+    entityServer,
+} from "@gateway/api";
+import { loadTwoFactorConfig } from "./config.ts";
+import twoFactorRoutes from "./routes.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default fp(
+    async (app: FastifyInstance) => {
+        if (!loadTwoFactorConfig()) {
+            app.log.info("2FA plugin: disabled (config.json enabled=false)");
+            return;
+        }
+
+        // entities/account.json 의 totp 필드를 account 엔티티에 additive-sync
+        await ensurePluginEntities(__dirname).catch((err) =>
+            app.log.warn({ err }, "2FA: entity setup failed, continuing"),
+        );
+
+        // 탈퇴 시 totp 필드 초기화 (account 컬럼 방식이므로 별도 테이블 없음)
+        registerWithdrawHook("2fa", async (accountSeq) => {
+            await entityServer.submit("account", {
+                seq: accountSeq,
+                totp_secret: null,
+                totp_enabled: false,
+                totp_enabled_time: null,
+                totp_recovery_codes: null,
+                totp_failed_attempts: 0,
+                totp_locked_until: null,
+            });
+        });
+
+        await app.register(twoFactorRoutes, { prefix: "/api/v1/account/2fa" });
+    },
+    { name: "2fa-plugin" },
+);

package/src/app/plugins/2fa/routes.ts

@@ -0,0 +1,49 @@
+/**
+ * 2FA (TOTP) 라우트 서브 플러그인
+ *
+ * index.ts 에서 prefix `/api/v1/account/2fa` 로 등록된다.
+ * 최종 엔드포인트:
+ *
+ *   POST   /api/v1/account/2fa/setup                — 2FA 설정 시작 (JWT 필요)
+ *   POST   /api/v1/account/2fa/setup/verify         — 2FA 활성화 확인 (JWT 또는 setup_token)
+ *   DELETE /api/v1/account/2fa                      — 2FA 비활성화 (JWT 필요)
+ *   GET    /api/v1/account/2fa/status               — 2FA 상태 조회 (JWT 필요)
+ *   POST   /api/v1/account/2fa/recovery/regenerate  — 복구 코드 재생성 (JWT 필요)
+ *   POST   /api/v1/account/2fa/verify               — 2단계 TOTP 검증 (two_factor_token)
+ *   POST   /api/v1/account/2fa/recovery             — 복구 코드로 로그인 (two_factor_token)
+ *
+ * Go `internal/router/auth_routes.go` /v1/auth/2fa/* 포팅
+ */
+
+import type { FastifyInstance } from "fastify";
+import { loadTwoFactorConfig } from "./config.ts";
+import {
+    createSetupHandler,
+    createSetupVerifyHandler,
+    createVerifyHandler,
+    createRecoveryHandler,
+    createDisableHandler,
+    createStatusHandler,
+    createRegenerateHandler,
+} from "./handlers/index.ts";
+
+export default async function twoFactorRoutes(
+    app: FastifyInstance,
+): Promise<void> {
+    const cfg = loadTwoFactorConfig();
+
+    if (!cfg) {
+        return;
+    }
+
+    // ── JWT 필요 엔드포인트 ─────────────────────────────────────────────────
+    app.post("/setup", createSetupHandler(cfg));
+    app.post("/setup/verify", createSetupVerifyHandler(cfg));
+    app.delete("/", createDisableHandler(cfg));
+    app.get("/status", createStatusHandler(cfg));
+    app.post("/recovery/regenerate", createRegenerateHandler(cfg));
+
+    // ── two_factor_token 사용 (JWT 불필요) ─────────────────────────────────
+    app.post("/verify", createVerifyHandler(cfg));
+    app.post("/recovery", createRecoveryHandler(cfg));
+}

package/src/app/plugins/2fa/templates/auth/2fa_disabled.html

@@ -0,0 +1,23 @@
+<h2 style="margin: 0 0 16px; font-size: 22px; font-weight: 700; color: #1a1a2e;">2단계 인증이 비활성화되었습니다</h2>
+<p style="margin: 0 0 16px; font-size: 15px; color: #555; line-height: 1.6;">
+    <strong>${email}</strong> 계정의 2단계 인증(TOTP)이 해제되었습니다.<br>
+    앞으로 이메일과 비밀번호만으로 로그인됩니다.
+</p>
+
+<div style="margin: 0 0 24px; padding: 20px; background-color: #f8d7da; border-radius: 8px; border-left: 4px solid #dc3545;">
+    <p style="margin: 0; font-size: 14px; color: #721c24; line-height: 1.6;">
+        <strong>보안 알림:</strong> 2단계 인증이 해제되면 계정 보안 수준이 낮아집니다.<br>
+        가능하면 다시 2단계 인증을 설정하는 것을 권장합니다.
+    </p>
+</div>
+
+<p style="margin: 0 0 8px; font-size: 14px; color: #888; line-height: 1.6;">
+    해제 시각: ${disabled_time}
+</p>
+<p style="margin: 0 0 8px; font-size: 14px; color: #888; line-height: 1.6;">
+    해제 방법: ${disabled_by|본인 요청}
+</p>
+
+<p style="margin: 0; font-size: 13px; color: #aaa; line-height: 1.6;">
+    본인이 해제하지 않은 경우, 즉시 비밀번호를 변경하고 관리자에게 문의하세요.
+</p>

package/src/app/plugins/2fa/templates/auth/2fa_recovery_regenerated.html

@@ -0,0 +1,31 @@
+<h2 style="margin: 0 0 16px; font-size: 22px; font-weight: 700; color: #1a1a2e;">복구 코드가 재생성되었습니다</h2>
+<p style="margin: 0 0 16px; font-size: 15px; color: #555; line-height: 1.6;">
+    <strong>${email}</strong> 계정의 2단계 인증 복구 코드가 새로 생성되었습니다.<br>
+    이전 복구 코드는 모두 <strong>폐기</strong>되었습니다.
+</p>
+
+<div style="margin: 0 0 24px; padding: 20px; background-color: #fff3cd; border-radius: 8px; border-left: 4px solid #ffc107;">
+    <p style="margin: 0 0 8px; font-size: 14px; font-weight: 700; color: #856404;">⚠ 새 복구 코드를 안전한 곳에 저장하세요</p>
+    <p style="margin: 0; font-size: 13px; color: #856404; line-height: 1.5;">
+        각 코드는 <strong>한 번만</strong> 사용할 수 있으며, 이 이메일 이후에는 다시 확인할 수 없습니다.
+    </p>
+</div>
+
+<div style="text-align: center; margin: 0 0 24px;">
+    <table role="presentation" cellpadding="0" cellspacing="0" style="margin: 0 auto;">
+        <tr>
+            <td style="padding: 16px 32px; background-color: #f0f0f5; border-radius: 8px;">
+                <pre style="margin: 0; font-size: 18px; font-weight: 700; color: #1a1a2e; font-family: 'Courier New', monospace; letter-spacing: 2px; line-height: 2;">${recovery_codes}</pre>
+            </td>
+        </tr>
+    </table>
+</div>
+
+<p style="margin: 0 0 16px; font-size: 14px; color: #888; line-height: 1.6;">
+    새 복구 코드: <strong>${recovery_count|10}개</strong><br>
+    재생성 시각: ${regenerated_time}
+</p>
+
+<p style="margin: 0; font-size: 13px; color: #aaa; line-height: 1.6;">
+    본인이 요청하지 않은 경우, 계정이 보안 위협에 노출되었을 수 있습니다. 즉시 비밀번호를 변경하고 관리자에게 문의하세요.
+</p>

package/src/app/plugins/2fa/templates/auth/2fa_setup_complete.html

@@ -0,0 +1,43 @@
+<h2 style="margin: 0 0 16px; font-size: 22px; font-weight: 700; color: #1a1a2e;">2단계 인증이 활성화되었습니다</h2>
+<p style="margin: 0 0 16px; font-size: 15px; color: #555; line-height: 1.6;">
+    <strong>${email}</strong> 계정에 2단계 인증(TOTP)이 설정되었습니다.<br>
+    앞으로 로그인 시 Authenticator 앱의 인증 코드가 필요합니다.
+</p>
+
+<div style="margin: 0 0 24px; padding: 20px; background-color: #fff3cd; border-radius: 8px; border-left: 4px solid #ffc107;">
+    <p style="margin: 0 0 8px; font-size: 14px; font-weight: 700; color: #856404;">⚠ 복구 코드를 안전한 곳에 저장하세요</p>
+    <p style="margin: 0 0 12px; font-size: 13px; color: #856404; line-height: 1.5;">
+        Authenticator 앱에 접근할 수 없는 경우 아래 복구 코드로 로그인할 수 있습니다.<br>
+        각 코드는 <strong>한 번만</strong> 사용할 수 있으며, 이 이메일 이후에는 다시 확인할 수 없습니다.
+    </p>
+</div>
+
+<div style="text-align: center; margin: 0 0 24px;">
+    <table role="presentation" cellpadding="0" cellspacing="0" style="margin: 0 auto;">
+        <tr>
+            <td style="padding: 16px 32px; background-color: #f0f0f5; border-radius: 8px;">
+                <pre style="margin: 0; font-size: 18px; font-weight: 700; color: #1a1a2e; font-family: 'Courier New', monospace; letter-spacing: 2px; line-height: 2;">${recovery_codes}</pre>
+            </td>
+        </tr>
+    </table>
+</div>
+
+<p style="margin: 0 0 8px; font-size: 14px; color: #888; line-height: 1.6;">
+    남은 복구 코드: <strong>${recovery_count|10}개</strong>
+</p>
+<p style="margin: 0 0 16px; font-size: 14px; color: #888; line-height: 1.6;">
+    설정 시각: ${enabled_time}
+</p>
+
+<div style="margin: 0 0 16px; padding: 16px; background-color: #f8f9fa; border-radius: 6px;">
+    <p style="margin: 0; font-size: 13px; color: #666; line-height: 1.6;">
+        💡 <strong>권장 사항</strong><br>
+        • 복구 코드를 출력하거나 비밀번호 관리자에 저장하세요<br>
+        • 복구 코드가 3개 이하로 줄면 재생성하세요<br>
+        • 본인이 설정하지 않았다면 즉시 비밀번호를 변경하세요
+    </p>
+</div>
+
+<p style="margin: 0; font-size: 13px; color: #aaa; line-height: 1.6;">
+    본인이 설정하지 않은 경우, 계정이 보안 위협에 노출되었을 수 있습니다. 즉시 비밀번호를 변경하고 관리자에게 문의하세요.
+</p>

package/src/app/plugins/2fa/totp-utils.ts

@@ -0,0 +1,189 @@
+/**
+ * TOTP (RFC 6238) + 복구 코드 유틸리티
+ *
+ * Go `internal/security/totp.go`에서 포팅.
+ * Node.js 내장 crypto 모듈만 사용 (외부 의존성 없음).
+ * QR코드 생성만 `qrcode` 패키지 사용.
+ */
+
+import { createHmac, randomBytes, createHash } from "node:crypto";
+import QRCode from "qrcode";
+
+/* ──────────── Base32 ──────────── */
+
+const BASE32_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+/** Base32 인코딩 (NoPadding, RFC 4648) */
+function base32Encode(buf: Buffer): string {
+    let result = "";
+    let bits = 0;
+    let value = 0;
+    for (let i = 0; i < buf.length; i++) {
+        value = (value << 8) | buf[i];
+        bits += 8;
+        while (bits >= 5) {
+            result += BASE32_CHARS[(value >>> (bits - 5)) & 0x1f];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        result += BASE32_CHARS[(value << (5 - bits)) & 0x1f];
+    }
+    return result;
+}
+
+/** Base32 디코딩 (NoPadding, 대소문자 무시) */
+function base32Decode(str: string): Buffer {
+    const s = str.toUpperCase().replace(/=+$/, "");
+    let bits = 0;
+    let value = 0;
+    const output: number[] = [];
+    for (let i = 0; i < s.length; i++) {
+        const idx = BASE32_CHARS.indexOf(s[i]);
+        if (idx === -1) continue; // 잘못된 문자 무시
+        value = (value << 5) | idx;
+        bits += 5;
+        if (bits >= 8) {
+            output.push((value >>> (bits - 8)) & 0xff);
+            bits -= 8;
+        }
+    }
+    return Buffer.from(output);
+}
+
+/* ──────────── TOTP ──────────── */
+
+/**
+ * HMAC-SHA1 기반 HOTP 코드 생성
+ * Go `generateCode()` 포팅
+ */
+function generateHOTP(
+    secretBytes: Buffer,
+    step: bigint,
+    digits: number,
+): string {
+    const stepBuf = Buffer.alloc(8);
+    stepBuf.writeBigUInt64BE(BigInt(step));
+
+    const mac = createHmac("sha1", secretBytes);
+    mac.update(stepBuf);
+    const sum = mac.digest();
+
+    const offset = sum[sum.length - 1] & 0x0f;
+    const code =
+        ((sum[offset] & 0x7f) << 24) |
+        ((sum[offset + 1] & 0xff) << 16) |
+        ((sum[offset + 2] & 0xff) << 8) |
+        (sum[offset + 3] & 0xff);
+
+    const mod = Math.pow(10, digits);
+    return String(code % mod).padStart(digits, "0");
+}
+
+/** 20바이트(160-bit) 랜덤 비밀 키 생성 → Base32 인코딩 */
+export function generateSecret(): string {
+    const secret = randomBytes(20);
+    return base32Encode(secret);
+}
+
+/** otpauth:// URI 생성 */
+export function generateOTPAuthURL(
+    secret: string,
+    email: string,
+    issuer: string,
+    digits: number,
+    period: number,
+): string {
+    return `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(email)}?secret=${secret}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=${digits}&period=${period}`;
+}
+
+/**
+ * TOTP 코드 검증 (skew 허용)
+ * Go `ValidateTOTP()` 포팅
+ */
+export function validateTOTP(
+    secret: string,
+    code: string,
+    skew: number,
+    digits: number,
+    period: number,
+): boolean {
+    let secretBytes: Buffer;
+    try {
+        secretBytes = base32Decode(secret);
+    } catch {
+        return false;
+    }
+
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    const currentStep = now / BigInt(period);
+
+    for (let i = -skew; i <= skew; i++) {
+        const step = currentStep + BigInt(i);
+        const expected = generateHOTP(secretBytes, step, digits);
+        if (expected === code.trim()) return true;
+    }
+    return false;
+}
+
+/**
+ * otpauth URL → QR코드 data URI (PNG base64)
+ * Go `GenerateSetupQR()` 포팅
+ */
+export async function generateSetupQR(
+    otpauthURL: string,
+    size = 256,
+): Promise<string> {
+    const dataURL = await QRCode.toDataURL(otpauthURL, {
+        width: size,
+        errorCorrectionLevel: "H",
+    });
+    return dataURL;
+}
+
+/* ──────────── 복구 코드 ──────────── */
+
+/**
+ * 복구 코드 N개 생성 (8자리 HEX)
+ * Go `GenerateRecoveryCodes()` 포팅
+ * 평문 코드 + SHA-256 해시 목록 반환
+ */
+export function generateRecoveryCodes(count: number): {
+    plainCodes: string[];
+    hashes: string[];
+} {
+    const plainCodes: string[] = [];
+    const hashes: string[] = [];
+    for (let i = 0; i < count; i++) {
+        const b = randomBytes(4);
+        const code = b
+            .readUInt32BE(0)
+            .toString(16)
+            .padStart(8, "0")
+            .toUpperCase();
+        plainCodes.push(code);
+        const hash = createHash("sha256").update(code).digest("hex");
+        hashes.push(`sha256:${hash}`);
+    }
+    return { plainCodes, hashes };
+}
+
+/**
+ * 복구 코드 검증
+ * Go `VerifyRecoveryCode()` 포팅
+ * 일치하면 해당 해시를 제거한 나머지 목록을 반환
+ */
+export function verifyRecoveryCode(
+    code: string,
+    hashes: string[],
+): { valid: boolean; remaining: string[] } {
+    const normalized = code.trim().toUpperCase();
+    const inputHash = `sha256:${createHash("sha256").update(normalized).digest("hex")}`;
+    for (let i = 0; i < hashes.length; i++) {
+        if (hashes[i] === inputHash) {
+            const remaining = [...hashes.slice(0, i), ...hashes.slice(i + 1)];
+            return { valid: true, remaining };
+        }
+    }
+    return { valid: false, remaining: hashes };
+}

package/src/app/plugins/2fa/types.ts

@@ -0,0 +1,95 @@
+/**
+ * 2FA (TOTP) 라우트 타입 정의
+ */
+
+export interface TwoFactorConfig {
+    /** 2FA 기능 활성화 여부 */
+    enabled: boolean;
+    /** TOTP 발급자 이름 (Authenticator 앱에 표시) */
+    issuer: string;
+    /** TOTP 코드 자릿수 (기본 6) */
+    code_digits: number;
+    /** TOTP 주기 (초, 기본 30) */
+    period_sec: number;
+    /** 허용 시간 오차 (step 수, 기본 1) */
+    skew: number;
+    /** 복구 코드 개수 (기본 10) */
+    recovery_code_count: number;
+    /** setup_token TTL (초, 기본 300) */
+    setup_token_ttl_sec: number;
+    /** 최대 TOTP 검증 실패 횟수 (기본 5) */
+    max_verify_attempts: number;
+    /** 잠금 지속 시간 (초, 기본 300) */
+    verify_lockout_sec: number;
+    /** JWT 액세스 토큰 TTL (초) — Go jwt.json과 일치시킬 것 */
+    jwt_access_ttl_sec: number;
+    /** JWT 리프레시 토큰 TTL (초) */
+    jwt_refresh_ttl_sec: number;
+    /** JWT 발급자 */
+    jwt_issuer: string;
+}
+
+/* ──────────── 계정 엔티티 필드 ──────────── */
+
+export interface AccountTotpFields {
+    seq: number;
+    email: string;
+    name?: string;
+    rbac_role?: string;
+    license_seq?: number;
+    has_password?: boolean | number;
+    passwd?: string;
+    totp_enabled?: boolean;
+    totp_secret?: string;
+    totp_enabled_time?: string;
+    totp_recovery_codes?: string;
+    totp_failed_attempts?: number;
+    totp_locked_until?: string;
+}
+
+/* ──────────── 요청 바디 ──────────── */
+
+export interface SetupVerifyBody {
+    code: string;
+    setup_token?: string;
+}
+
+export interface TwoFactorVerifyBody {
+    two_factor_token: string;
+    code: string;
+}
+
+export interface TwoFactorRecoveryBody {
+    two_factor_token: string;
+    recovery_code: string;
+}
+
+export interface TwoFactorDisableBody {
+    passwd?: string;
+    code: string;
+}
+
+export interface RegenerateRecoveryBody {
+    code: string;
+}
+
+/* ──────────── JWT 클레임 ──────────── */
+
+export interface TwoFactorTokenClaims {
+    purpose: "2fa_verify" | "2fa_setup";
+    sub: string;
+    exp: number;
+    iat: number;
+    iss?: string;
+}
+
+export interface AccessTokenClaims {
+    email: string;
+    name: string;
+    rbac_role: string;
+    license_seq: number;
+    sub: string;
+    exp: number;
+    iat: number;
+    iss?: string;
+}

package/src/app/plugins/README.md

@@ -0,0 +1,118 @@
+# app/plugins/
+
+Fastify 플러그인 모음. 서버 시작 시 알파벳 순으로 자동 로드됩니다.
+
+## 구조
+
+```
+{plugin}/
+├── config.json          — 플러그인 활성화 여부 + 설정값 (enabled: true/false, minify: false)
+├── config.example.json  — 설정 예시 (빌드 시 config.json 으로 배포)
+├── config.ts            — config.json 로더 (enabled: false 이면 null 반환)
+├── index.ts             — Fastify 플러그인 진입점 (fastify-plugin 래퍼)
+├── routes.ts            — /v1/api/{plugin}/* 라우트 테이블
+├── handlers.ts          — 요청/응답 처리
+├── service.ts           — 비즈니스 로직
+├── entity-adapter.ts    — Go 엔티티 서버 쿼리 어댑터 (entityServer 래퍼)
+├── types/               — TypeScript 타입 정의
+│   └── index.ts
+├── entities/            — 플러그인이 사용하는 엔티티 설정 JSON
+│   └── {entity_name}.json
+└── providers/           — 외부 서비스 클라이언트 (pg·llm·ocr·alimtalk·identity)
+    ├── index.ts         — 프로바이더 팩토리
+    └── {name}.ts        — 개별 프로바이더 구현
+```
+
+## 핵심 규칙
+
+- `config.json`의 `enabled: false` 이면 플러그인이 로드되지 않습니다.
+- `index.ts`는 반드시 `fastify-plugin` (`fp()`)으로 래핑해야 합니다.
+- `config.example.json`은 빌드 시 `config.json`으로 교체되어 배포됩니다.
+- 실제 `config.json`은 Git에 커밋하지 않습니다 (`.gitignore` 적용).
+
+## models/ 폴더 (계획)
+
+> **현재 미구현.** 향후 엔티티 타입 선언을 `models/` 폴더로 통합할 계획입니다.  
+> 현재는 타입이 각 플러그인의 `types/` 혹은 `entity-adapter.ts` 에 직접 선언됩니다.
+
+도입 시 아래 구조를 사용할 예정:
+
+| 파일 패턴          | 용도                                                                               | 예시               |
+| ------------------ | ---------------------------------------------------------------------------------- | ------------------ |
+| `{entity_name}.ts` | **단독 소유** — 플러그인이 생성·관리하는 테이블 전체 타입 (`Table`, `Data`, `Row`) | `account_oauth.ts` |
+
+## entities/ 폴더
+
+플러그인이 의존하는 엔티티 JSON을 `entities/` 폴더에 배치하면,
+서버 시작 시 `ensurePluginEntities()`가 자동으로 Go 엔티티 서버에 등록합니다.
+이미 등록된 엔티티는 `already_exists`로 스킵되어 덮어씌워지지 않습니다.
+
+```ts
+import { ensurePluginEntities } from "@system/utils/ensure-entities.ts";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const pluginDir = path.dirname(fileURLToPath(import.meta.url));
+await ensurePluginEntities(pluginDir);
+```
+
+## Go 서버 패스스루 오버라이드
+
+`plugins/{name}/routes.ts` 에 등록된 라우트는 **항상 Go 서버 패스스루보다 먼저 처리**됩니다.
+
+앱 서버의 라우트 로딩 순서:
+
+```
+loadExtensionPlugins()  ← plugins/*/index.ts (Fastify 플러그인)
+registerRoutes()        ← plugins/*/routes.ts + routes/*/route.ts  ← 여기서 처리되면 Go 서버로 전달되지 않음
+registerProxyRoutes()   ← /api/v1/{prefix}/* 를 Go 서버로 패스스루 (나머지만)
+```
+
+예를 들어 `plugins/smtp/routes.ts`에 `POST /send`를 등록하면,
+`/api/v1/smtp/send`는 앱 서버가 직접 처리하고 Go 서버로 전달되지 않습니다.
+`/api/v1/smtp/`의 그 외 경로는 계속 패스스루됩니다.
+
+이 우선순위는 `plugins/`와 `routes/` 모두 동일하게 적용됩니다.
+
+## 배포 제외 (deploy)
+
+`config.json`에 `"deploy": false`를 설정하면 빌드 시 해당 플러그인이 dist에 포함되지 않습니다.
+기본값은 `true`입니다. 개발 중이거나 특정 환경에서만 쓰는 플러그인을 배포 빌드에서 제외할 때 사용합니다.
+
+```json
+{ "enabled": true, "deploy": false }
+```
+
+## 난독화 (minify)
+
+`config.json`에 `"minify": true`를 설정하면 빌드 시 해당 플러그인의 JS 파일만
+esbuild로 난독화됩니다. `npm run build:minify-plugins`로 적용됩니다.
+
+```json
+{ "enabled": true, "minify": true }
+```
+
+## 플러그인 목록
+
+| 플러그인   | 설명                      | 문서                                        |
+| ---------- | ------------------------- | ------------------------------------------- |
+| 2fa        | TOTP 2단계 인증           | [docs](../../../docs/plugins/2fa.md)        |
+| alimtalk   | 카카오 알림톡             | [docs](../../../docs/plugins/alimtalk.md)   |
+| example    | 플러그인 개발 템플릿      | —                                           |
+| friendtalk | 카카오 친구톡             | [docs](../../../docs/plugins/friendtalk.md) |
+| holidays   | 공휴일 자동 동기화        | [docs](../../../docs/plugins/holidays.md)   |
+| identity   | 본인인증 (NICE·KMC·Danal) | [docs](../../../docs/plugins/identity.md)   |
+| llm        | LLM 연동 (OpenAI 등)      | [docs](../../../docs/plugins/llm.md)        |
+| oauth      | 소셜 로그인 + 계정 연동   | [docs](../../../docs/plugins/oauth.md)      |
+| ocr        | OCR 문서 인식             | [docs](../../../docs/plugins/ocr.md)        |
+| pg         | 결제 PG                   | [docs](../../../docs/plugins/pg.md)         |
+| push       | 푸시 알림                 | [docs](../../../docs/plugins/push.md)       |
+| sms        | SMS 발송                  | [docs](../../../docs/plugins/sms.md)        |
+| taxinvoice | 전자세금계산서            | [docs](../../../docs/plugins/taxinvoice.md) |
+
+## 상세 문서
+
+- [플러그인 추가 가이드](../../../docs/plugins/how-to-create.md)
+- [플러그인 구조 가이드](../../../docs/plugins/how-to-create.md)
+- [라우트 레퍼런스](../../../docs/routes/README.md)
+- [설정 파일 가이드](../../../docs/configs.md)

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

@@ -0,0 +1,7 @@
+{
+    "enabled": true,
+    "apiKey": "${AIS_API_KEY}",
+    "collectSeconds": 60,
+    "batchSize": 20,
+    "comment": "aisstream.io 무료 API key: https://aisstream.io (GitHub 로그인 후 apikeys 메뉴)"
+}

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

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { AisConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+export function loadAisConfig(): AisConfig | null {
+    if (!existsSync(CONFIG_PATH)) return null;
+
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8").replace(
+            /\$\{([^}]+)\}/g,
+            (_m, name) => process.env[name] ?? "",
+        );
+        const cfg = JSON.parse(raw) as AisConfig;
+        if (cfg.enabled === false) {
+            logger.info("ais plugin disabled in config");
+            return null;
+        }
+        if (!cfg.apiKey) {
+            logger.warn("ais: apiKey not set, plugin disabled");
+            return null;
+        }
+        return cfg;
+    } catch (err) {
+        logger.error({ err }, "ais: failed to load config");
+        return null;
+    }
+}