@gaonjs/config 0.19.0 → 0.22.0

package/README.md

@@ -1,6 +1,6 @@
 # @gaonjs/config
 
-Gaon 루트 설정 로더 · 자동 배선 (§3.3 · M9-A).
+Gaon 루트 설정 로더 · 자동 배선 (§3.3).
 
 - `defineConfig()` — 사용자가 `gaon.config.ts` 에서 쓰는 타입 안전 헬퍼
 - `loadGaonConfig(cwd)` — `<cwd>/gaon.config.ts` 를 동적 import

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;
 }
@@ -98,6 +104,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 {
@@ -140,6 +154,18 @@ export interface AppSessionConfig {
      * 쓴 defineAppConfig 리터럴이 excess-property 컴파일 에러였다).
      */
     readonly csrf?: boolean;
+    /**
+     * 쿠키 Secure 토글(결정 295). 생략 시 NODE_ENV==='production' 이면 켬. 운영인데
+     * 비-TLS(사내 내부망 http 등)로 서빙하면 Secure 쿠키가 안 실려 로그인이 조용히
+     * 실패한다 — 그 경우에만 `false` 로 명시한다(웹 레이어는 지원했는데 이 전달
+     * 통로가 없어 우회로가 없었다 · 결정 271 csrf 누락과 동형 표류).
+     */
+    readonly secure?: boolean;
+    /**
+     * 쿠키 SameSite(결정 295). 생략 시 'lax'. `'none'` 은 스펙상 Secure 필수라
+     * secure 가 꺼져 있으면 부팅 에러(웹 레이어 가드 · 브라우저 조용한 쿠키 거부 방지).
+     */
+    readonly sameSite?: 'lax' | 'strict' | 'none';
 }
 /**
  * 앱별 설정 — apps/<app>/app.config.ts (v0.16 §3.3).
@@ -178,6 +204,7 @@ export interface AppConfig {
      */
     readonly seal?: boolean | {
         readonly except?: readonly string[];
+        readonly strictQuery?: boolean;
     };
     /**
      * 결정 150: 앱 전역 공유 prop 제공자. 요청마다 실행돼 반환 객체가 이 앱의 모든 렌더
@@ -186,6 +213,15 @@ 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 없음).
+     */
+    readonly security?: AppSecurityOptions;
 }
 /** 타입 안전 헬퍼 — `export default defineAppConfig({...})`. */
 export declare function defineAppConfig(config: AppConfig): AppConfig;

package/dist/wire.js

@@ -177,11 +177,19 @@ 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 등)라면 둘 다 제거하세요.`);
+        }
         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,
@@ -217,6 +225,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 +351,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` 게이팅으로
@@ -346,6 +377,12 @@ async function assembleApp(config, root, domain, redis, nats) {
                     // app.config 의 CSRF 토글을 serve 로 전달한다(SessionOptions.csrf · 명시적으로만 끔).
                     // 이전엔 wireGaon 이 이 필드를 떨궈 documented 토글이 gaon serve 에서 무시됐다.
                     csrf: ac.session.csrf,
+                    // 결정 295: 쿠키 secure·sameSite 도 전달한다 — 웹 레이어(AppSessionOptions)는
+                    // 지원했는데 이 통로가 떨궈 운영 비-TLS(secure:false)·sameSite 조정의 우회로가
+                    // 없었다(결정 271 csrf 누락과 동형). sameSite:'none'+secure 미충족은 웹 레이어가
+                    // 부팅 에러로 막는다(assertSameSiteSecure).
+                    secure: ac.session.secure,
+                    sameSite: ac.session.sameSite,
                 },
             };
         }
@@ -368,6 +405,12 @@ 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 를 없앤다.
+        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,
@@ -462,6 +505,34 @@ 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) {
+    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;
+        const abs = d.root.startsWith('/') ? d.root : join(root, d.root);
+        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 });
+    }
+    return out;
+}
 function storageCspOrigins(storage) {
     if (!storage)
         return undefined;

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@gaonjs/config",
-  "version": "0.19.0",
+  "version": "0.22.0",
   "description": "Gaon 루트 설정 로더·자동 배선 (gaon.config.ts)",
   "type": "module",
   "license": "MIT",
   "homepage": "https://gaonjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.nyx-zone.com/gaon/framework.git",
+    "directory": "packages/config"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -25,14 +30,14 @@
   ],
   "dependencies": {
     "ioredis": "^5.4.1",
-    "@gaonjs/adapter-mongo": "0.1.0",
+    "@gaonjs/adapter-mongo": "0.3.0",
     "@gaonjs/core": "0.2.4",
+    "@gaonjs/async": "0.17.0",
+    "@gaonjs/data": "0.24.0",
     "@gaonjs/i18n": "0.2.4",
-    "@gaonjs/mail": "0.3.3",
-    "@gaonjs/async": "0.15.3",
+    "@gaonjs/web": "0.27.0",
     "@gaonjs/storage": "0.1.5",
-    "@gaonjs/data": "0.21.0",
-    "@gaonjs/web": "0.21.0"
+    "@gaonjs/mail": "0.4.0"
   },
   "devDependencies": {
     "fastify": "^5.0.0"