@gaonjs/config 0.20.0 → 0.23.0

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionConfig } from '@gaonjs/data';
-import type { SecurityOptions, ClientIpConfig } from '@gaonjs/web';
+import type { SecurityOptions, AppSecurityOptions, ClientIpConfig } from '@gaonjs/web';
 import type { AuthOptions, JwtAuthOptions, SharedPropsFn } from '@gaonjs/web';
 /**
  * DB 커넥션 맵 — 키는 커넥션 이름(§4.5), 값은 어댑터 설정. `main` 은 관례
@@ -33,6 +33,12 @@ export interface MailConfig {
     readonly user?: string;
     readonly pass?: string;
     readonly secure?: boolean;
+    /**
+     * 결정 357: STARTTLS 를 **강제**한다(서버가 STARTTLS 를 광고하지 않으면 전송 실패).
+     * 기본(생략)은 기회적 STARTTLS — 운영 SMTP 에서 다운그레이드로 자격이 평문 노출될 수
+     * 있으니, 자격 있는 운영 전송은 `secure: true`(465) 또는 `requireTls: true` 를 켠다.
+     */
+    readonly requireTls?: boolean;
     /** from 헤더 기본값. */
     readonly defaultFrom?: string;
 }
@@ -41,6 +47,12 @@ export type StorageDiskConfig = {
     readonly driver: 'local';
     readonly root: string;
     readonly publicUrl?: string;
+    /**
+     * 결정 401: 공개 서빙 범위. 이 접두사 아래 키만 `publicUrl` 경로로 응답하고
+     * 나머지는 404 다(생략 시 'public/'). 로컬 디스크는 한 폴더에 공개·비공개가
+     * 섞이므로 접두사가 유일한 경계다 — `''` 로 두면 디스크 전체가 무인증 공개.
+     */
+    readonly publicPrefix?: string;
 } | {
     readonly driver: 's3';
     readonly bucket: string;
@@ -98,6 +110,14 @@ export interface WebConfig {
      * `{ proxy: 1 }`(신뢰 홉 수) · `{ header: 'cf-connecting-ip' }`(신뢰 헤더).
      */
     readonly clientIp?: ClientIpConfig;
+    /**
+     * 결정 356: 업로드(multipart) 한도. 생략 시 파일당 10MB · 최대 10개.
+     * `false` 는 multipart 파싱 비활성. 한도 초과는 413 + 수리 안내로 응답된다.
+     */
+    readonly uploads?: {
+        readonly maxFileSize?: number;
+        readonly maxFiles?: number;
+    } | false;
 }
 /** 루트 설정 — gaon.config.ts 의 defineConfig 인자. */
 export interface GaonConfig {
@@ -190,6 +210,7 @@ export interface AppConfig {
      */
     readonly seal?: boolean | {
         readonly except?: readonly string[];
+        readonly strictQuery?: boolean;
     };
     /**
      * 결정 150: 앱 전역 공유 prop 제공자. 요청마다 실행돼 반환 객체가 이 앱의 모든 렌더
@@ -198,6 +219,20 @@ export interface AppConfig {
      *   sharedProps: (ctx) => ({ locale: ctx.session?.locale ?? 'en' })
      */
     readonly sharedProps?: SharedPropsFn;
+    /**
+     * 결정 339: 이 앱만의 보안 override — CORS·rate limit. 생략한 필드는 전역
+     * (`gaon.config.ts` 의 `web.security`)을 상속한다. API 앱만 크로스 오리진을 열고
+     * web 앱의 same-origin 기본은 유지하는 용도:
+     *   security: { cors: { origin: 'https://app.example.com' }, rateLimit: { max: 600 } }
+     * `false` 는 이 앱에서 그 방어를 끈다(명시적으로만 · 규칙 8). 보안 응답 헤더는
+     * 전역 전용(앱 override 없음).
+     *
+     * 결정 389: override 객체는 전역과 **필드 단위 병합**이다 — `rateLimit: {
+     * timeWindow: '10 minutes' }` 처럼 일부만 줘도 `max` 는 전역(없으면 코어 기본)을
+     * 상속한다. CORS 는 `origin` 미명시 시 전역/코어 기본(`origin:false`)이 유지된다
+     * (fail-closed — 부분 override 로 CORS 가 열리지 않는다).
+     */
+    readonly security?: AppSecurityOptions;
 }
 /** 타입 안전 헬퍼 — `export default defineAppConfig({...})`. */
 export declare function defineAppConfig(config: AppConfig): AppConfig;

package/dist/wire.js

@@ -177,11 +177,26 @@ export async function configureNonDbBatteries(config, cwd = process.cwd(), opts
     // mail — SMTP 전송(개발·테스트는 MailPit sink, 운영은 실 SMTP).
     if (config.mail) {
         const m = config.mail;
+        // 결정 357: user/pass 반쪽 설정은 fail-loud — 이전엔 `user && pass` 게이팅으로 auth 가
+        // 무신호 드랍돼(익명 전송 시도) "설정했는데 인증이 안 걸리는" 조용한 오배선이었다.
+        if (!!m.user !== !!m.pass) {
+            throw new Error(`mail 설정에 user/pass 가 한쪽만 있습니다 (auth 는 둘 다 필요) — 반쪽 설정은 인증 없이 전송을 시도합니다.\n` +
+                `  → gaon.config.ts 의 mail 블록에 ${m.user ? 'pass' : 'user'} 를 함께 설정하거나(.env 의 SMTP_USER/SMTP_PASS),\n` +
+                `  → 인증 없는 SMTP(MailPit 등)라면 둘 다 제거하세요.`);
+        }
+        // 결정 404: secure(implicit TLS · 465)면 nodemailer 가 requireTLS 를 무시한다 —
+        // 연결은 이미 암호화라 위험은 없지만, 켠 설정이 아무 일도 안 하는 걸 모르면
+        // "STARTTLS 를 강제했다" 는 오해가 남는다. 부팅 경고로만 알린다(정당한 설정이라 throw 아님).
+        if (m.secure && m.requireTls) {
+            log.warn('mail.requireTls 는 secure: true 에서 무시됩니다 — secure(465)는 이미 암호화 연결로 시작합니다. ' +
+                'STARTTLS 강제가 목적이면 secure 를 끄고 requireTls 만 켜세요(587).');
+        }
         configureMailer({
             transport: smtpTransport({
                 host: m.host,
                 port: m.port,
                 secure: m.secure,
+                requireTls: m.requireTls,
                 auth: m.user && m.pass ? { user: m.user, pass: m.pass } : undefined,
             }),
             defaultFrom: m.defaultFrom,
@@ -192,10 +207,7 @@ export async function configureNonDbBatteries(config, cwd = process.cwd(), opts
         const disks = {};
         for (const [name, d] of Object.entries(config.storage.disks)) {
             if (d.driver === 'local') {
-                // root 는 프로젝트 상대 경로면 cwd 로 절대화.
-                const base = d.root.startsWith('/') ? d.root : join(root, d.root);
-                const root2 = opts.localRootFor ? opts.localRootFor(base) : base;
-                disks[name] = localDisk({ root: root2, baseUrl: d.publicUrl });
+                disks[name] = localDisk({ root: localDiskRoot(d.root, root, opts.localRootFor), baseUrl: d.publicUrl });
             }
             else {
                 disks[name] = s3Disk({
@@ -217,6 +229,24 @@ export async function configureNonDbBatteries(config, cwd = process.cwd(), opts
         const dir = config.i18n.dir ?? 'locales';
         const abs = dir.startsWith('/') ? dir : join(root, dir);
         const resources = loadLocales(abs);
+        // 결정 353: i18n 을 켰는데 카탈로그가 비면 fail-loud — 이전엔 무경고로 부팅해
+        // 모든 t() 가 원문 키를 화면에 노출했다(배포 이미지 locales 누락·dir 오타 무신호).
+        if (Object.keys(resources).length === 0) {
+            throw new Error(`i18n 이 설정됐지만 로케일 카탈로그가 비어 있습니다: ${abs}\n` +
+                `  → ${dir}/${config.i18n.fallbackLng}.json 을 만들거나(최소 fallbackLng 카탈로그),\n` +
+                `  → gaon.config.ts 의 i18n.dir 이 실제 카탈로그 폴더를 가리키는지 확인하세요.\n` +
+                `  (이 상태로 부팅하면 모든 t() 가 번역 대신 원문 키를 노출합니다 — 결정 353)`);
+        }
+        // 결정 353: fallbackLng·supportedLngs 가 지목한 로케일 파일이 통째로 없으면 fail-loud —
+        // 이전엔 협상이 그 로케일을 골라 주고 전 키가 fallback 언어로 폴백돼, 로케일 하나가
+        // 조용히 다른 언어로 나갔다(locale-parity 는 존재 파일만 비교해 못 잡는 사각).
+        const missing = [config.i18n.fallbackLng, ...(config.i18n.supportedLngs ?? [])].filter((lng, i, arr) => arr.indexOf(lng) === i && !resources[lng]);
+        if (missing.length > 0) {
+            throw new Error(`i18n 설정이 지목한 로케일의 카탈로그 파일이 없습니다: ${missing.join(', ')}\n` +
+                `  → ${dir}/ 에 ${missing.map((l) => `${l}.json`).join(' · ')} 을 추가하거나,\n` +
+                `  → gaon.config.ts 의 fallbackLng/supportedLngs 에서 해당 로케일을 제거하세요.\n` +
+                `  (파일이 없는 로케일은 전 화면이 fallback 언어로 조용히 대체됩니다 — 결정 353)`);
+        }
         await configureI18n({
             resources,
             fallbackLng: config.i18n.fallbackLng,
@@ -325,6 +355,11 @@ async function assembleApp(config, root, domain, redis, nats) {
         if (typeof ac?.sharedProps === 'function') {
             spec = { ...spec, sharedProps: ac.sharedProps };
         }
+        // 결정 339: app.config 의 앱 스코프 보안 override(CORS·rate limit)를 전달한다 —
+        // 생략 필드는 전역(web.security) 상속. createApp 이 앱 스코프 단위로 등록한다.
+        if (ac?.security && typeof ac.security === 'object') {
+            spec = { ...spec, security: ac.security };
+        }
         if (ac?.session?.secret) {
             // 결정 263: 세션이 구성됐는데(session.secret) Redis 가 없으면 fail-loud 한다.
             // 세션 저장소는 Redis 가 필수인데(redisSessionStore), 이전엔 `&& redis` 게이팅으로
@@ -374,6 +409,14 @@ async function assembleApp(config, root, domain, redis, nats) {
         security: config.web?.security,
         // 결정 131: 스토리지 오리진 CSP 자동 배선(설정 있으면 img-src·connect-src 에 부착).
         storageOrigins: storageCspOrigins(config.storage),
+        // 결정 355: 로컬 디스크 공개 경로(`/storage/<key>`)를 프레임웍이 직접 서빙 —
+        // url() 이 만드는 좌표를 아무도 응답하지 않던 조용한 404 를 없앤다.
+        // 결정 405: root 계산은 디스크 배선과 **같은 헬퍼**(localDiskRoot)를 쓴다 — serve
+        // 경로엔 테스트 격리 훅이 없지만(wireGaon 표면에 없음), 계산이 한 곳이라 갈라지지 않는다.
+        localStorage: localStorageServeTargets(config.storage, root),
+        // 결정 356: 업로드 한도 config 표면(web.uploads) — 이전엔 createApp 옵션만 있고
+        // wireGaon 이 전달하지 않아 정본 경로(gaon.config.ts)로 한도를 올릴 방법이 없었다.
+        uploads: config.web?.uploads,
         // 클라이언트 IP 정책(결정 120 · 생략 시 'direct'). 프록시 뒤 배치면 선언.
         clientIp: config.web?.clientIp,
         realtime: nats ? { nats, hubAddr: config.hub?.addr, heartbeatMs: config.hub?.heartbeatMs } : undefined,
@@ -468,6 +511,45 @@ void redisSessionStore;
  * 표시 오리진(img-src). 로컬 디스크는 same-origin 상대 URL 이라 CSP 와 무관(제외). 오리진은
  * `new URL(v).origin`(scheme+host+port) 만 — 경로·쿼리는 배제한다.
  */
+/**
+ * 결정 355: 상대 publicUrl(기본 '/storage')을 가진 로컬 디스크 → 루트 서빙 대상.
+ * 절대 URL(별도 서버/CDN)은 앱이 서빙하지 않는다. 같은 경로에 다른 root 가 겹치면
+ * fail-loud(어느 디스크가 응답할지 비결정 — 조용한 오서빙 방지).
+ */
+function localStorageServeTargets(storage, root, localRootFor) {
+    if (!storage)
+        return [];
+    const out = [];
+    for (const [name, d] of Object.entries(storage.disks)) {
+        if (d.driver !== 'local')
+            continue;
+        const urlPrefix = d.publicUrl ?? '/storage';
+        if (!urlPrefix.startsWith('/'))
+            continue;
+        // 결정 405: 디스크 배선과 **같은 헬퍼**로 root 를 계산한다 — 테스트 격리
+        // (localRootFor)가 한쪽에만 걸리면 업로드 위치와 서빙 위치가 어긋난다.
+        const abs = localDiskRoot(d.root, root, localRootFor);
+        const dup = out.find((o) => o.urlPrefix === urlPrefix);
+        if (dup) {
+            if (dup.root !== abs) {
+                throw new Error(`storage 로컬 디스크 '${name}' 의 publicUrl('${urlPrefix}')이 다른 로컬 디스크와 겹칩니다(root 는 다름).\n` +
+                    `  → 디스크마다 publicUrl 을 다르게 지정하세요(예: '/storage-${name}').`);
+            }
+            continue;
+        }
+        out.push({ urlPrefix, root: abs, publicPrefix: d.publicPrefix });
+    }
+    return out;
+}
+/**
+ * 로컬 디스크의 실 저장 루트 — 상대 경로는 프로젝트 루트 기준으로 절대화하고,
+ * 테스트 격리 훅(localRootFor)을 적용한다. 디스크 배선과 공개 서빙이 이 한 지점을
+ * 공유해야 두 좌표가 갈라지지 않는다(결정 405).
+ */
+function localDiskRoot(diskRoot, root, localRootFor) {
+    const base = diskRoot.startsWith('/') ? diskRoot : join(root, diskRoot);
+    return localRootFor ? localRootFor(base) : base;
+}
 function storageCspOrigins(storage) {
     if (!storage)
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/config",
-  "version": "0.20.0",
+  "version": "0.23.0",
   "description": "Gaon 루트 설정 로더·자동 배선 (gaon.config.ts)",
   "type": "module",
   "license": "MIT",
@@ -30,14 +30,14 @@
   ],
   "dependencies": {
     "ioredis": "^5.4.1",
-    "@gaonjs/async": "0.16.0",
-    "@gaonjs/adapter-mongo": "0.2.0",
+    "@gaonjs/adapter-mongo": "0.4.0",
+    "@gaonjs/async": "0.18.0",
     "@gaonjs/core": "0.2.4",
-    "@gaonjs/i18n": "0.2.4",
-    "@gaonjs/data": "0.22.0",
-    "@gaonjs/mail": "0.3.3",
+    "@gaonjs/i18n": "0.3.0",
+    "@gaonjs/mail": "0.5.0",
+    "@gaonjs/data": "0.25.0",
     "@gaonjs/storage": "0.1.5",
-    "@gaonjs/web": "0.24.1"
+    "@gaonjs/web": "0.29.0"
   },
   "devDependencies": {
     "fastify": "^5.0.0"