feat(backend): 파일 업로드 공통 골격 추가 (로컬 디스크)

템플릿이 나중에 반드시 필요해질 공용 기능을 미리 갖춘다. multer 취약점을 해소한 김에, 안전한 업로드 기준도 함께 세운다. - modules/upload — 단일 파일 업로드 엔드포인트(POST /api/files)와 재사용 가능한 검증 설정 - 확장자와 MIME 을 **둘 다** 검사하는 허용목록 방식. 확장자만 보면 위장이 쉽고, MIME 만 보면 클라이언트가 보낸 값이라 신뢰할 수 없다. .html/.svg/.js 등 브라우저가 실행할 수 있는 형식은 허용 목록에서 제외. - 저장 파일명은 서버가 UUID 로 생성한다. 클라이언트 파일명을 경로에 쓰면 경로 탈출이 가능하다. - 크기 한도(UPLOAD_MAX_SIZE_MB, 기본 5MB) 초과 시 FILE_002(413). - 도메인 에러 코드 FILE_001/FILE_002 추가 후 세 플랫폼 사전 동기화. 함께 고친 것: - 전역 필터가 프레임워크의 영문 메시지를 그대로 노출하고 있었다. 크기 초과 시 multer 의 "File too large" 가 사용자에게 보였다 — 이제 코드에 대응하는 레지스트리 문구만 사용하며, 재정의는 BusinessException 으로만 가능하다. - sync:error-codes 가 컨테이너 안에서 실행되면 형제 디렉터리를 찾지 못해 cryptic 한 mkdir 오류를 냈다. 원인과 해결 방법을 알리도록 보강. - 업로드 볼륨 경로에 compose 기본값을 주어 기존 .env 에 키가 없어도 동작하게 함. 실제 multipart 요청으로 정상 업로드·형식 거부·MIME 위장·경로 탈출 시도·크기 초과· 파일 누락 시나리오를 모두 검증했다. 알려진 한계(확장자·MIME 검사는 파일 내용을 보지 않는다)는 security.md 에 명시하고, 업로드 디렉터리를 정적 서빙하지 말 것을 규칙으로 남겼다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-17 21:47:10 +09:00
parent 750cd6362a
commit aba274e56f
22 changed files with 463 additions and 23 deletions
@@ -40,6 +40,7 @@
        "@swc/core": "^1.15.24",
        "@types/express": "^5.0.0",
        "@types/jest": "^30.0.0",
+        "@types/multer": "^2.2.0",
        "@types/node": "^22.10.7",
        "@types/supertest": "^6.0.2",
        "chokidar": "^5.0.0",
@@ -176,6 +177,24 @@
        "url": "https://github.com/sponsors/epoberezkin"
      }
    },
+    "node_modules/@angular-devkit/schematics-cli/node_modules/chokidar": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+      "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "readdirp": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 14.16.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
    "node_modules/@angular-devkit/schematics-cli/node_modules/json-schema-traverse": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -183,6 +202,22 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@angular-devkit/schematics-cli/node_modules/readdirp": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+      "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "engines": {
+        "node": ">= 14.18.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
    "node_modules/@angular-devkit/schematics-cli/node_modules/rxjs": {
      "version": "7.8.1",
      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz",
@@ -248,6 +283,24 @@
        "url": "https://github.com/sponsors/epoberezkin"
      }
    },
+    "node_modules/@angular-devkit/schematics/node_modules/chokidar": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+      "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "readdirp": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 14.16.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
    "node_modules/@angular-devkit/schematics/node_modules/json-schema-traverse": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -255,6 +308,22 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@angular-devkit/schematics/node_modules/readdirp": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+      "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "engines": {
+        "node": ">= 14.18.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
    "node_modules/@angular-devkit/schematics/node_modules/rxjs": {
      "version": "7.8.1",
      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz",
@@ -3023,6 +3092,24 @@
        "url": "https://github.com/sponsors/epoberezkin"
      }
    },
+    "node_modules/@nestjs/schematics/node_modules/chokidar": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+      "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "readdirp": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 14.16.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
    "node_modules/@nestjs/schematics/node_modules/json-schema-traverse": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -3030,6 +3117,22 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@nestjs/schematics/node_modules/readdirp": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+      "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "engines": {
+        "node": ">= 14.18.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
    "node_modules/@nestjs/schematics/node_modules/rxjs": {
      "version": "7.8.1",
      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz",
@@ -3431,7 +3534,7 @@
      "version": "1.15.41",
      "resolved": "https://registry.npmjs.org/@swc/core/-/core-1.15.41.tgz",
      "integrity": "sha512-03nQq/082QRJJiOvp3FGbgxTGyyxMxohPTjhk/W9bD2J0tk4ukITI7goOhOO2WbaHn/lsPmo/zf8+DIXhwpgYQ==",
-      "devOptional": true,
+      "dev": true,
      "hasInstallScript": true,
      "license": "Apache-2.0",
      "dependencies": {
@@ -3475,6 +3578,7 @@
      "cpu": [
        "arm64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3491,6 +3595,7 @@
      "cpu": [
        "x64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3507,6 +3612,7 @@
      "cpu": [
        "arm"
      ],
+      "dev": true,
      "license": "Apache-2.0",
      "optional": true,
      "os": [
@@ -3523,6 +3629,7 @@
      "cpu": [
        "arm64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3539,6 +3646,7 @@
      "cpu": [
        "arm64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3555,6 +3663,7 @@
      "cpu": [
        "ppc64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3571,6 +3680,7 @@
      "cpu": [
        "s390x"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3587,6 +3697,7 @@
      "cpu": [
        "x64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3603,6 +3714,7 @@
      "cpu": [
        "x64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3619,6 +3731,7 @@
      "cpu": [
        "arm64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3635,6 +3748,7 @@
      "cpu": [
        "ia32"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3651,6 +3765,7 @@
      "cpu": [
        "x64"
      ],
+      "dev": true,
      "license": "Apache-2.0 AND MIT",
      "optional": true,
      "os": [
@@ -3664,14 +3779,14 @@
      "version": "0.1.3",
      "resolved": "https://registry.npmjs.org/@swc/counter/-/counter-0.1.3.tgz",
      "integrity": "sha512-e2BR4lsJkkRlKZ/qCHPw9ZaSxc0MVUd7gtbtaB7aMvHeJVYe8sOB8DBZkP2DtISHGSku9sCK6T6cnY0CtXrOCQ==",
-      "devOptional": true,
+      "dev": true,
      "license": "Apache-2.0"
    },
    "node_modules/@swc/types": {
      "version": "0.1.26",
      "resolved": "https://registry.npmjs.org/@swc/types/-/types-0.1.26.tgz",
      "integrity": "sha512-lyMwd7WGgG79RS7EERZV3T8wMdmPq3xwyg+1nmAM64kIhx5yl+juO2PYIHb7vTiPgPCj8LYjsNV2T5wiQHUEaw==",
-      "devOptional": true,
+      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
        "@swc/counter": "^0.1.3"
@@ -3938,6 +4053,16 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@types/multer": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@types/multer/-/multer-2.2.0.tgz",
+      "integrity": "sha512-3U1troeqGV8Ntp7Q3klwf4zr23VEoqYVocYXaswm9+8z3O9UHDYAqLxjJ/h550iRADTjKdOdhhasXw6gD6kYtg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/express": "*"
+      }
+    },
    "node_modules/@types/node": {
      "version": "22.19.21",
      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.21.tgz",