Node.js、Express、Multer による安全な画像アップロード API
アップロードしたファイルは、バイト列の検証に合格してからダウンロード可能にすべきです。この例では、JPEG または PNG を一つ受信し、隔離領域に保持して ClamAV でスキャンし、Sharp でデコードしてから、Express のダウンロードルートで元のファイルを公開します。拒否されたファイルは、このルートでは公開しません。
作成するのは、サーバー側のアップロードパイプラインをテストする開発者向けの、ローカル画像アップロード API です。127.0.0.1 でのみ待ち受け、最大 5 MiB のファイルを受け入れ、画像メタデータを含め、受け入れたバイト列を保持します。ユーザーアカウントやファイルごとの認可機能はありません。アプリケーションにこれらの制御を実装するまでは、ローカルでのみ使用してください。
Node.js 環境のセットアップ
Linux と、Node.js 26.13.0 LTS またはそれ以降の保守対象の Node.js 26 リリース、Docker、cURL を使用します。26.13.0 には、2026年10月21日のセキュリティ修正が含まれます。この例全体は、2026年11月7日に Node.js 26.13.0、Corepack 0.34.5、Yarn 4.12.0 で再検証しました。それ以前の2026年9月24日のテストでは Node.js 26.8.1 を使用しました。
Corepack は別途インストールしてください。Node.js 26 には同梱されていません。この検証済みの構成では、0.34.5 をインストールします。
npm install --global corepack@0.34.5
以下のプロジェクトでは、Corepack を通じて Yarn 4.12.0 を選択します。Node.js に必要なメモリに加えて、ClamAV コンテナー用に 4 GiB のメモリを確保してください。隔離ディレクトリをマウントできるよう、Docker デーモンはこのマシン上で動かす必要があります。
新しいプロジェクトを作成します。&& の連鎖は、ディレクトリがすでに存在する場合や、セットアップのいずれかの処理が失敗した場合に停止します。サブシェルを使うため、失敗しても元の作業ディレクトリは変わりません。既存のディレクトリを削除せず、別のプロジェクト名を選んでください。ローカルの Yarn 設定は、上位プロジェクトの yarnPath によって別の実行ファイルが選ばれることも防ぎます。生成されたロックファイルは保持してください。
(
mkdir image-upload-api &&
cd image-upload-api &&
printf '%s\n' '{"name":"image-upload-api","private":true,"type":"module","packageManager":"yarn@4.12.0"}' > package.json &&
touch yarn.lock &&
printf '%s\n' 'nodeLinker: node-modules' 'ignorePath: true' > .yarnrc.yml &&
corepack yarn add --exact express@5.2.1 multer@2.4.0 sharp@0.35.4 express-rate-limit@8.7.0 &&
corepack yarn add --dev --exact @types/express@5.0.6 @types/multer@2.2.0 @types/node@26.6.2
) && cd image-upload-api
Multer 2.4.0 またはそれ以降の修正済みリリースを使用してください。2.2.0 から 2.3.0 では、非同期ストレージコールバックがパスを割り当てる前にクライアントが切断すると、孤立したファイルが残ることがあります。メンテナーのアドバイザリでは、2.4.0 で修正されたことが示されています。アプリケーションのエラー処理だけでは、このライブラリの競合状態は解消できません。
アップロードファイルのウイルススキャン
新しいプロジェクトディレクトリから、非公開のスキャナーを起動します。このバージョン固定の ClamAV 1.5.4 イメージには、シグネチャデータベースが含まれています。コンテナーにはネットワークアクセスも公開ポートもなく、隔離フォルダーだけを読み取り専用でマウントします。アプリケーションは Docker を通じて、コンテナー内の clamdscan を呼び出します。
mkdir -m 700 quarantine accepted &&
docker run --detach --rm --name image-upload-clamav \
--memory 4g --network none --env CLAMAV_NO_FRESHCLAMD=true \
--mount "type=bind,source=$PWD/quarantine,target=/scan,readonly" \
clamav/clamav@sha256:0e31ce089574268aefa0b543767d66b70240ab51ed49eec53e07f18d5629d817
デーモンがデータベースを読み込むのを待ってから、API を起動してください。
docker exec image-upload-clamav clamdscan --ping 120:1 &&
docker exec image-upload-clamav clamdscan --version
2026年9月24日のテストでは、2026年9月20日付のデータベース 28129 が報告されました。テスト時点では四日前のデータベースです。11月7日の再実行でも、同じ日付のデータベースを使用しました。FreshClam を無効にしているため、これはオフラインのデモであり、継続的に更新されるスキャンサービスではありません。クリーンという判定は、これらのシグネチャでマルウェアが検出されなかったことを意味します。ファイルが無害であることを保証するものではありません。デプロイしたサービスでは、シグネチャを最新に保ち、スキャナーの稼働状態を監視してください。公式 Docker ガイドに、データベースの更新とメモリ要件の説明があります。
基本的な API エンドポイント構造の作成
以下の完全なプログラムを、プロジェクトディレクトリに
app.ts として保存してください。Node はこの TypeScript ファイルを直接実行します。ホスト側のパスをスキャナーのマウントと一致させるため、同じディレクトリから起動してください。
スキャナーは、検査対象のファイルについて、スキャンに成功し、明示的にクリーンと判定された結果だけを受け入れます。コンテナーがない場合、デーモンエラー、タイムアウト、予期しない応答が発生した場合は、アップロードを拒否します。--fdpass により、clamdscan が非公開ファイルを開き、そのファイル記述子を Unix ソケット経由でデーモンに渡せます。ClamAV のスキャンドキュメントを参照してください。
import { execFile } from 'node:child_process'
import { randomBytes } from 'node:crypto'
import { link, mkdir, rm, writeFile } from 'node:fs/promises'
import { resolve } from 'node:path'
import express, { type ErrorRequestHandler } from 'express'
import { rateLimit } from 'express-rate-limit'
import multer from 'multer'
import sharp from 'sharp'
process.umask(0o077)
const quarantine = resolve('quarantine')
const accepted = resolve('accepted')
const container = process.env.CLAMAV_CONTAINER ?? 'image-upload-clamav'
const port = Number(process.env.PORT ?? 3000)
const app = express()
let activeUploads = 0
class UploadError extends Error {
status: number
constructor(status: number, message: string) {
super(message)
this.status = status
}
}
function scanFile(filename: string): Promise<void> {
const path = `/scan/${filename}`
return new Promise((resolveScan, reject) => {
execFile('docker', ['exec', container, 'clamdscan', '--fdpass', '--no-summary', path],
{ timeout: 30_000, maxBuffer: 64 * 1024 }, (error, stdout) => {
const result = stdout.trim()
if (!error && result === `${path}: OK`) return resolveScan()
if (error?.code === 1 && result.startsWith(`${path}: `) && result.endsWith(' FOUND')) {
return reject(new UploadError(422, 'Malware detected.'))
}
reject(new UploadError(503, 'Scanner unavailable or scan inconclusive.'))
})
})
}
const receive = multer({
storage: multer.diskStorage({
destination: quarantine,
filename(_req, _file, callback) {
randomBytes(16, (error, bytes) => {
if (error) return callback(error, '')
callback(null, bytes.toString('hex'))
})
},
}),
limits: { fileSize: 5 * 1024 * 1024, files: 1, fields: 0, parts: 2 },
fileFilter(_req, file, callback) {
if (file.mimetype !== 'image/jpeg' && file.mimetype !== 'image/png') {
return callback(new UploadError(415, 'Send a JPEG or PNG image.'))
}
callback(null, true)
},
}).single('image')
const uploadLimiter = rateLimit({
windowMs: 15 * 60 * 1000,
limit: 10,
standardHeaders: 'draft-8',
legacyHeaders: false,
message: { error: 'Upload limit reached. Try again after 15 minutes.' },
})
app.disable('x-powered-by')
app.use((_req, res, next) => {
res.set({ 'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'no-store' })
next()
})
app.post('/upload', uploadLimiter, async (req, res) => {
if (activeUploads >= 2) throw new UploadError(503, 'Two uploads are already processing.')
activeUploads += 1
// An absolute deadline also covers a client that keeps sending tiny chunks.
const deadline = setTimeout(() => res.destroy(), 60_000)
let publishedPath: string | undefined
let committed = false
try {
await new Promise<void>((done, reject) => {
receive(req, res, (error: unknown) => error ? reject(error) : done())
})
if (!req.file) throw new UploadError(400, 'Use the multipart file field named image.')
await scanFile(req.file.filename)
const decoder = sharp(req.file.path, { limitInputPixels: 12_000_000, failOn: 'warning' })
const metadata = await decoder.metadata().catch(() => {
throw new UploadError(415, 'Image headers are invalid or exceed 12 megapixels.')
})
if (metadata.format !== 'jpeg' && metadata.format !== 'png') {
throw new UploadError(415, 'Only JPEG and PNG files are accepted.')
}
const mime = metadata.format === 'jpeg' ? 'image/jpeg' : 'image/png'
if (mime !== req.file.mimetype) throw new UploadError(415, 'Image bytes and MIME type differ.')
await decoder.raw().toBuffer().catch(() => {
throw new UploadError(415, 'Image pixels could not be decoded.')
})
if (req.aborted || res.destroyed) return
const filename = `${req.file.filename}.${metadata.format === 'jpeg' ? 'jpg' : 'png'}`
const destination = resolve(accepted, filename)
// A hard link publishes the complete file atomically and refuses an existing name.
await link(req.file.path, destination)
publishedPath = destination
if (req.aborted || res.destroyed) return
await rm(req.file.path)
res.status(201).json({ filename, size: req.file.size, url: `/images/${filename}` })
committed = true
} finally {
clearTimeout(deadline)
try {
// Multer may already have removed the file and cleared its path after a later part fails.
if (req.file?.path) await rm(req.file.path, { force: true })
if (publishedPath && !committed) await rm(publishedPath, { force: true })
} finally {
activeUploads -= 1
}
}
})
app.get('/images/:filename', (req, res, next) => {
const { filename } = req.params
if (!/^[a-f0-9]{32}\.(jpg|png)$/.test(filename)) {
throw new UploadError(404, 'Image not found.')
}
res.download(resolve(accepted, filename), filename, (error) => {
if (!error) return
if (res.headersSent) return next(error)
next(new UploadError(404, 'Image not found.'))
})
})
const handleError: ErrorRequestHandler = (error: unknown, _req, res, next) => {
if (res.headersSent) return next(error)
if (res.destroyed) return
const status = error instanceof UploadError ? error.status
: error instanceof multer.MulterError ? (error.code === 'LIMIT_FILE_SIZE' ? 413 : 400)
: 500
const message = error instanceof UploadError ? error.message
: status === 413 ? 'File exceeds 5 MiB.' : 'Upload could not be processed.'
console.error('Request failed', { status })
res.status(status).json({ error: message })
}
app.use(handleError)
async function main(): Promise<void> {
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new Error('PORT must be an integer from 1 to 65535.')
}
await mkdir(accepted, { recursive: true, mode: 0o700 })
const probe = `probe-${randomBytes(16).toString('hex')}`
await writeFile(resolve(quarantine, probe), 'Scanner readiness check\n', { flag: 'wx' })
try {
await scanFile(probe)
} finally {
await rm(resolve(quarantine, probe), { force: true })
}
app.listen(port, '127.0.0.1', (error?: Error) => {
if (error) {
console.error('Cannot bind API port; choose an unused PORT.')
process.exitCode = 1
return
}
console.log(`Ready at http://127.0.0.1:${port}`)
})
}
main().catch((error: unknown) => {
console.error(error instanceof UploadError ? error.message
: 'Startup failed. Check PORT, directories, and the scanner mount.')
process.exitCode = 1
})
公開前のバイト列の検証
Multer は multipart の構造と 5 MiB の上限を処理します。MIME フィルターは、クライアントが指定したラベルを初期段階で確認するものです。続いて Sharp が検出した形式をそのラベルと照合し、ピクセルをデコードします。photo.png という名前のテキストファイルは合格しません。元のファイル名をストレージパスに使うことはありません。ダウンロード時の拡張子は、検出した形式から決定します。
Sharp の metadata() は、ピクセルデータをデコードせずにヘッダーを読み取ります。そのため、この例では
raw().toBuffer() も呼び出します。Sharp がデコードするのはデフォルトの画像であり、APNG ファイルのすべてのアニメーションフレームを検証するわけではありません。デコードしたバッファーは破棄するため、保存したファイルはアップロード時とバイト単位で一致します。12メガピクセルの上限と厳格なデコードにより、リソースへのリスクを軽減します。ただし、ネイティブデコーダーを隔離するサンドボックスではありません。Sharp とそのネイティブライブラリには、常に修正を適用してください。GIF、SVG、その他の形式は、この例で受け入れる入力の対象外です。
同時に受信、スキャン、またはデコードできるアップロードは二つです。それを超えるアップロードには 503 を返します。60秒の期限に達するとクライアント接続を閉じますが、すでに実行中のネイティブ処理は完了してからスロットを解放します。IP 制限では、拒否された試行も含め、15分あたり十回の試行を許可します。メモリ内のカウンターはプロセスの再起動でリセットされ、サーバー間では共有されません。どちらの制限も、アカウント単位のクォータや、受け入れたファイルの累積数の上限を設けるものではありません。
API の起動と失敗の解釈
スキャナーの準備が整ったら、サーバーをフォアグラウンドで起動します。
node app.ts
Ready at http://127.0.0.1:3000 を待ってください。起動時には、ポートを開く前に、マウントした隔離ディレクトリを通じて実際のスキャンを行います。ポート 3000 が使用中の場合は、PORT=3007 node app.ts で別のポートを選び、cURL コマンドでもそのポートを使用してください。Express 5 は、バインドエラーを
app.listen コールバックに渡します。その場合、このプログラムは準備完了の URL を出力せず、失敗の終了ステータスで終了します。
| ステータス | 意味 |
|---|---|
201 | スキャンとデコードが完了し、返された URL から元のバイト列を取得できます。 |
400 | ファイルの欠落、予期しないフィールド、またはファイルサイズ以外の Multer multipart 制限です。 |
413 | ファイルが 5 MiB を超えています。 |
415 | 非対応の MIME タイプ、バイト列の不一致、不正な画像、またはピクセル上限違反です。 |
422 | ClamAV がマルウェアを検出しました。 |
429 | この IP からのアップロード試行が多すぎます。 |
503 | スキャナーの障害、またはすでに二つのアップロードを処理中です。 |
500 | 予期しない解析エラー、ファイルシステム障害、またはサーバー障害です。 |
通常の拒否されたリクエストでは、ファイルを隔離領域から削除します。修正済みの Multer は、非同期のファイル名コールバックも含め、中断された書き込みも処理します。ただし、プロセスのクラッシュや強制終了では、隔離ファイルが残ることがあります。それらの確認と削除は、API を停止している間だけ行ってください。受け入れたファイルをサーバーが確定すると、クライアントが応答を受信できなくても、ファイルは保存されたままです。
cURL による API のテスト
プロジェクトディレクトリで別のターミナルを開きます。サンプル画像をダウンロードせずに、小さく有効な PNG を作成します。次の処理は、既存の sample.png の上書きを拒否します。
node --input-type=module -e '
import { writeFile } from "node:fs/promises";
import sharp from "sharp";
const image = await sharp({ create: { width: 2, height: 2, channels: 3, background: "red" } }).png().toBuffer();
await writeFile("sample.png", image, { flag: "wx" });
'
アップロードしてから、JSON 応答の URL を使ってダウンロードします。シェルの noclobber 設定により、このブロックは既存の結果ファイルへの書き込みを拒否します。各リクエストは、この実行で作成したばかりのファイルにのみ書き込み、リクエストが失敗した場合はそのファイルを削除します。再度成功させるには、新しいファイル名を使ってください。cmp は、ダウンロードしたバイト列が元のバイト列と一致すると、何も出力せずに正常終了します。
(
set -euC
: > upload.json
curl --fail-with-body --silent --show-error \
-F 'image=@sample.png;type=image/png' http://127.0.0.1:3000/upload >| upload.json || { rm -- upload.json; exit 1; }
image_url=$(node --input-type=module -e '
import { readFile } from "node:fs/promises";
const result = JSON.parse(await readFile("upload.json", "utf8"));
if (!/^\/images\/[a-f0-9]{32}\.(jpg|png)$/.test(result.url)) throw new Error("Invalid upload response");
console.log(result.url);
')
: > downloaded.png
curl --fail --silent --show-error "http://127.0.0.1:3000$image_url" >| downloaded.png || { rm -- downloaded.png; exit 1; }
cmp sample.png downloaded.png
)
応答が失われる前にアップロードが確定した可能性がある場合は、再試行する前に
accepted を確認してください。再度アップロードすると別のファイルが作成されます。ダウンロードが失敗しても、有効な受領記録 upload.json は残るため、再アップロードせずに、記録された URL で再試行できます。
拒否動作を簡単に確認するには、プロジェクトのマニフェストを PNG と偽って送信します。
curl --silent --show-error --write-out '\nHTTP %{http_code}\n' \
-F 'image=@package.json;filename=photo.png;type=image/png' http://127.0.0.1:3000/upload
415 が返り、新しく受け入れたファイルがなく、リクエスト後の隔離ディレクトリが空であることを確認してください。API の実行中に docker stop image-upload-clamav でスキャナーを停止すると、有効な画像でも 503 が返ります。既存のプロジェクトディレクトリはそのままにして、前述の docker run
コマンドでスキャナーを再起動し、準備完了を待ってから再試行してください。
保持するデータとダウンロード権限の決定
二つのディレクトリは、静的 Web ルートの外側に配置します。公開にハードリンクを使えるよう、同じファイルシステム上に置きます。新しいファイルにアクセスできるのは、Node を実行する OS アカウントだけです。受け入れたファイルにはランダムな名前を付け、上書きはしません。同じ画像を再度アップロードすると、別のファイルを作成します。作業を終えたら、Ctrl+C で API を停止し、スキャナーも停止してください。どちらのディレクトリもディスク上に残るため、内容を確認したり、意図的に削除したりできます。
エラーログにはステータスコードを記録しますが、クライアントのファイル名やスキャナーの出力は含めません。ダウンロードルートは、nosniff と no-store を付けて添付ファイルとして配信します。EXIF、位置情報、末尾のバイト列、その他の埋め込みコンテンツは削除しません。スキャンとデコードの成功は、無害化よりも限定的な意味しか持ちません。正規化した公開画像が必要な場合は、別途再エンコード処理を追加し、その出力を公開する前に、処理のメタデータと形式のポリシーを検証してください。
このパイプラインを公開アプリケーションや非公開オブジェクトストアに接続する前に、認証、ファイルごとの認可、ストレージクォータ、保持ポリシーを追加してください。ランダムな URL や CORS は、所有権の確認にはなりません。Docker コマンドアダプターはローカルデモには便利ですが、Node プロセスに Docker デーモンへのアクセス権を与えます。デプロイしたサービスでは、権限をより限定した専用のスキャナー連携を使用してください。このチュートリアルでは、クラウドストレージへの経路の設定や検証は行いません。
