@aiquants/daily-report 0.6.2 → 0.7.0

package/src/server/handlers.attachment.spec.ts

@@ -0,0 +1,470 @@
+/**
+ * Authorization and delivery tests for the attachment endpoint.
+ * 添付エンドポイントの認可・配信テスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **`text/html` / `image/svg+xml` をインライン配信しない。** `file_type` は外部システム由来の
+ *   未検証値であり、自オリジンでインライン表示すると格納型 XSS になる。`nosniff` は
+ *   「宣言型から外れた推測」を止めるだけで、宣言された型の実行は止めない。
+ * - **「存在しない」と「他人の下書き」が応答としてバイト同一になる** (存在オラクル回避)。
+ * - **ログに `file_path` を出さない。**
+ */
+import { describe, expect, it, vi } from "vitest"
+import { asciiFallbackFileName, createDailyReportHandlers, encodeRfc8187, sanitizeMediaType } from "./handlers"
+import { makeAttachmentArgs, makeHandlersFixture, type TestAttachmentRow } from "./test-helpers/handlers-config"
+
+/** 可視な添付 1 件の既定形。 */
+const visibleRow = (over: Partial<TestAttachmentRow> = {}): TestAttachmentRow => ({
+    fileName: "report.png",
+    filePath: "gcs://bucket/path/report.png",
+    fileType: "image/png",
+    fileSize: 1024,
+    ...over,
+})
+
+/** 既定のバイト列 (3 バイト)。 */
+const threeBytes = () => new Uint8Array(new ArrayBuffer(3))
+
+describe("attachment loader / 認証と入口の検証", () => {
+    it("未認証は 401 を返し、配信用ヘッダーを一切出さない", async () => {
+        const { config } = makeHandlersFixture({ user: null })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(401)
+        expect(res.headers.get("Content-Disposition")).toBeNull()
+        expect(res.headers.get("Content-Type")).toBe("application/json")
+    })
+
+    it("GET / HEAD 以外のメソッドは 405 を返す", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow() })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1", { method: "POST" }))
+        expect(res.status).toBe(405)
+    })
+
+    it("ポート未注入の配備では全トークンが 404 になる (意図した縮退動作)", async () => {
+        const { config } = makeHandlersFixture({ omitPorts: true, attachment: visibleRow() })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(404)
+    })
+
+    it("復号できないトークンは 400、負値・0 も 400 を返す", async () => {
+        const handlers = createDailyReportHandlers(makeHandlersFixture({ attachment: visibleRow() }).config)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("not-a-token"))).status).toBe(400)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A0"))).status).toBe(400)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A-5"))).status).toBe(400)
+    })
+
+    it("安全整数域を超える ID へ復号されるトークンは 400 で止め、DB へ渡さない", async () => {
+        // 可逆難読化はトークンの正準性を検証しないため、正規トークンと同じ形の入力から
+        // 2^53 超の値が復号されうる。素通しすると SQL ドライバーの範囲検証が例外を投げ、
+        // 400 のはずが 500 になる (実測: sqids の 12 文字トークンで 1.6e19 が返る)
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow() })
+        const handlers = createDailyReportHandlers(config)
+        expect((await handlers.attachment.loader(makeAttachmentArgs(`A${Number.MAX_SAFE_INTEGER + 2}`))).status).toBe(400)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A1e300"))).status).toBe(400)
+        expect(calls.getAttachmentForUser).toEqual([])
+        // 境界そのもの (2^53-1) は正当な ID として通す
+        expect((await handlers.attachment.loader(makeAttachmentArgs(`A${Number.MAX_SAFE_INTEGER}`))).status).toBe(200)
+    })
+
+    it("内部ユーザー ID が解決できない場合は 403 を返す", async () => {
+        const { config } = makeHandlersFixture({ internalUserId: null, attachment: visibleRow() })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(403)
+    })
+
+    it("Set-Cookie を失敗分岐でも成功応答でも伝播する", async () => {
+        // 成功経路は fail() を通らず独立に append しているため、失敗分岐だけを見ても固定できない
+        const cookie = "session=abc; Path=/"
+        for (const options of [{ user: null }, { internalUserId: null }, { attachment: null }, { attachment: visibleRow() }] as const) {
+            const { config } = makeHandlersFixture({ cookie, ...options })
+            const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+            expect(res.headers.get("Set-Cookie")).toBe(cookie)
+        }
+    })
+})
+
+describe("attachment loader / 認可 (存在オラクル回避)", () => {
+    it("不可視な添付は 404 を返す", async () => {
+        const { config } = makeHandlersFixture({ attachment: null })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(404)
+    })
+
+    it("認可判定へ「添付 ID と閲覧者の内部ユーザー ID」をこの順で渡す", async () => {
+        // 唯一の認可境界は SQL 述語であり、その入力はこの 2 引数しかない。
+        // 閲覧者 ID を渡し忘れる / 取り違える欠陥は、ここを表明しないと一切検出できない
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow() })
+        await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A77"))
+        expect(calls.getAttachmentForUser).toEqual([[77, 42]])
+    })
+
+    it("「行が無い」と「他人の下書き」の応答がバイト同一になる", async () => {
+        // どちらもサービス層は null を返す。ハンドラーが区別しないことを表明する
+        const a = await createDailyReportHandlers(makeHandlersFixture({ attachment: null }).config).attachment.loader(makeAttachmentArgs("A1"))
+        const b = await createDailyReportHandlers(makeHandlersFixture({ attachment: null }).config).attachment.loader(makeAttachmentArgs("A2"))
+        expect(a.status).toBe(b.status)
+        expect(await a.text()).toBe(await b.text())
+        expect([...a.headers].sort()).toEqual([...b.headers].sort())
+    })
+
+    it("ストレージ側の not_found / denied / invalid_path も同じ 404 本文にする", async () => {
+        const bodies: string[] = []
+        for (const reason of ["not_found", "denied", "invalid_path"] as const) {
+            const { config } = makeHandlersFixture({ attachment: visibleRow(), readResult: { ok: false, reason } })
+            const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+            expect(res.status).toBe(404)
+            bodies.push(await res.text())
+        }
+        expect(new Set(bodies).size).toBe(1)
+    })
+
+    it("ストレージが not_found を返したとき実体消失を記録する", async () => {
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow(), readResult: { ok: false, reason: "not_found" } })
+        await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A77"))
+        expect(calls.markAttachmentMissing).toEqual([77])
+    })
+
+    it("denied では実体消失を記録しない (消えたわけではない)", async () => {
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow(), readResult: { ok: false, reason: "denied" } })
+        await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A77"))
+        expect(calls.markAttachmentMissing).toEqual([])
+    })
+
+    it("200 で配信できたら消失記録を解除する (absent からの唯一の自動回復経路)", async () => {
+        // 片方向だと一時障害で立った absent を利用者が自力で戻せない
+        // (UI は absent の添付にリンクを描画しないため再取得の手段が消える)
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow() })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A77"))
+        expect(res.status).toBe(200)
+        expect(calls.markAttachmentPresent).toEqual([77])
+        expect(calls.markAttachmentMissing).toEqual([])
+    })
+
+    it("失敗応答では実体存在を記録しない", async () => {
+        for (const reason of ["not_found", "denied", "unavailable", "too_large", "invalid_path"] as const) {
+            const { config, calls } = makeHandlersFixture({ attachment: visibleRow(), readResult: { ok: false, reason } })
+            await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A77"))
+            expect(calls.markAttachmentPresent, `reason=${reason}`).toEqual([])
+        }
+    })
+})
+
+describe("attachment loader / サイズと可用性", () => {
+    it("DB の既知サイズが上限を超える場合は読み取らずに 413 を返す", async () => {
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow({ fileSize: 999_999_999 }), attachmentMaxBytes: 1024 })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(413)
+        expect(calls.readAttachment).toHaveLength(0)
+    })
+
+    it("サイズ未知 (取込元が報告しない) でもポートの too_large を 413 へ写像する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileSize: null }), readResult: { ok: false, reason: "too_large" } })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(413)
+    })
+
+    it("unavailable は 502 を返す", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), readResult: { ok: false, reason: "unavailable" } })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(502)
+    })
+
+    it("レート上限を超えると 429 と Retry-After を返す", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), attachmentRateLimitPerMinute: 1 })
+        const handlers = createDailyReportHandlers(config)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A1"))).status).toBe(200)
+        const second = await handlers.attachment.loader(makeAttachmentArgs("A1"))
+        expect(second.status).toBe(429)
+        expect(second.headers.get("Retry-After")).toBe("60")
+    })
+
+    it("同時実行上限に達すると 503 と Retry-After を返す", async () => {
+        let release: (() => void) | undefined
+        const gate = new Promise<void>((resolve) => {
+            release = resolve
+        })
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), attachmentConcurrency: 1 })
+        const handlers = createDailyReportHandlers({
+            ...config,
+            readAttachment: async () => {
+                await gate
+                return { ok: true as const, bytes: threeBytes(), contentType: null }
+            },
+        })
+        const inFlight = handlers.attachment.loader(makeAttachmentArgs("A1"))
+        const rejected = await handlers.attachment.loader(makeAttachmentArgs("A2"))
+        expect(rejected.status).toBe(503)
+        expect(rejected.headers.get("Retry-After")).toBe("5")
+        release?.()
+        expect((await inFlight).status).toBe(200)
+    })
+})
+
+describe("attachment loader / Content-Type と Disposition (XSS 対策)", () => {
+    it("許可リスト内の型は宣言型のまま inline で配信する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileType: "image/png" }) })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("Content-Type")).toBe("image/png")
+        expect(res.headers.get("Content-Disposition")).toContain("inline")
+    })
+
+    it("text/html は octet-stream + attachment へ落とす (格納型 XSS の防止)", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileName: "evil.html", fileType: "text/html" }) })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("Content-Type")).toBe("application/octet-stream")
+        expect(res.headers.get("Content-Disposition")).toContain("attachment")
+    })
+
+    it("image/svg+xml も octet-stream + attachment へ落とす (SVG はスクリプトを含みうる)", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileName: "evil.svg", fileType: "image/svg+xml" }) })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("Content-Type")).toBe("application/octet-stream")
+        expect(res.headers.get("Content-Disposition")).toContain("attachment")
+    })
+
+    it("CR/LF を含む file_type でも 500 にせず既定 MIME へ落とす (許可リストが第 1 層として機能する)", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileType: "text/plain\r\nX-Injected: 1" }) })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(200)
+        expect(res.headers.get("Content-Type")).toBe("application/octet-stream")
+        expect(res.headers.get("X-Injected")).toBeNull()
+    })
+
+    it("非 ASCII を含む file_type でも 500 にせず既定 MIME へ落とす", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileType: 'application/pdf; name="あ"' }) })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(200)
+        expect(res.headers.get("Content-Type")).toBe("application/octet-stream")
+    })
+
+    it("DB の file_type が無いときはストレージ申告型へフォールバックする", async () => {
+        // サイズや MIME を DB に持たない取込元があるため、この分岐は実運用で通る
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileType: null }), readResult: { ok: true, bytes: threeBytes(), contentType: "image/png" } })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("Content-Type")).toBe("image/png")
+        expect(res.headers.get("Content-Disposition")).toContain("inline")
+    })
+
+    it("ストレージ申告型が許可リスト外なら octet-stream へ落とす", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileType: null }), readResult: { ok: true, bytes: threeBytes(), contentType: "text/html" } })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("Content-Type")).toBe("application/octet-stream")
+        expect(res.headers.get("Content-Disposition")).toContain("attachment")
+    })
+
+    it("DB の file_type はストレージ申告型より優先する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileType: "application/pdf" }), readResult: { ok: true, bytes: threeBytes(), contentType: "image/png" } })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("Content-Type")).toBe("application/pdf")
+    })
+
+    it("?download=1 は許可リスト内の型でも attachment にする", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileType: "image/png" }) })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1", { query: "?download=1" }))
+        expect(res.headers.get("Content-Disposition")).toContain("attachment")
+    })
+
+    it("日本語ファイル名を RFC 8187 で符号化し、ASCII フォールバックも併記する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow({ fileName: "報告書(1)'s *最終*.pdf", fileType: "application/pdf" }) })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        const disposition = res.headers.get("Content-Disposition") ?? ""
+        expect(disposition).toContain("filename*=UTF-8''")
+        expect(disposition).toContain('filename="')
+        // encodeURIComponent が残す ' ( ) * が符号化されていること
+        expect(disposition).not.toMatch(/filename\*=UTF-8''[^;]*[('*)]/)
+        // ASCII フォールバックに生の引用符が入っていないこと
+        expect(disposition).toMatch(/filename="[^"]*"/)
+    })
+
+    it("セキュリティヘッダーを 200 応答へ付与する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow() })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff")
+        expect(res.headers.get("Content-Security-Policy")).toBe("default-src 'none'; sandbox")
+        expect(res.headers.get("X-Frame-Options")).toBe("SAMEORIGIN")
+        expect(res.headers.get("Cache-Control")).toBe("private, no-store")
+        expect(res.headers.get("Content-Length")).toBe("3")
+    })
+})
+
+describe("attachment loader / HEAD と副作用", () => {
+    it("HEAD は本体を読まず、本文を返さない", async () => {
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow() })
+        const res = await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1", { method: "HEAD" }))
+        expect(res.status).toBe(200)
+        expect(res.body).toBeNull()
+        expect(calls.readAttachment[0]?.head).toBe(true)
+    })
+
+    it("HEAD の Content-Length は GET と一致する (RFC 9110 §9.3.2)", async () => {
+        // 本体を読まない HEAD ではポートが長さ 0 のビューを返すため、`bytes.byteLength` から
+        // 組み立てると必ず 0 になる。ポートが申告した `size` を使うことを固定する
+        const { config } = makeHandlersFixture({ attachment: visibleRow() })
+        const handlers = createDailyReportHandlers(config)
+        const get = await handlers.attachment.loader(makeAttachmentArgs("A1"))
+        const head = await handlers.attachment.loader(makeAttachmentArgs("A1", { method: "HEAD" }))
+        expect(get.headers.get("Content-Length")).toBe("3")
+        expect(head.headers.get("Content-Length")).toBe(get.headers.get("Content-Length"))
+    })
+
+    it("ポートが size を申告しない場合は実バイト長を使う", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow() })
+        const handlers = createDailyReportHandlers({ ...config, readAttachment: async () => ({ ok: true as const, bytes: new Uint8Array(new ArrayBuffer(7)), contentType: null }) })
+        const res = await handlers.attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.headers.get("Content-Length")).toBe("7")
+    })
+
+    it("読み取りポートへ内部パスと難読化済み principal を渡す", async () => {
+        const { config, calls } = makeHandlersFixture({ attachment: visibleRow() })
+        await createDailyReportHandlers(config).attachment.loader(makeAttachmentArgs("A1"))
+        expect(calls.readAttachment[0]?.filePath).toBe("gcs://bucket/path/report.png")
+        // 生の内部ユーザー ID ではなく難読化済みの値を渡すこと
+        expect(calls.readAttachment[0]?.principal).toBe("ENC42")
+    })
+
+    it("ログに file_path を出さない", async () => {
+        const lines: string[] = []
+        const logger = {
+            debug: (m?: unknown) => lines.push(String(m)),
+            info: (m?: unknown) => lines.push(String(m)),
+            warn: (m?: unknown) => lines.push(String(m)),
+            error: (m?: unknown) => lines.push(String(m)),
+        }
+        const { config } = makeHandlersFixture({ attachment: visibleRow() })
+        await createDailyReportHandlers({ ...config, logger }).attachment.loader(makeAttachmentArgs("A1"))
+        expect(lines.length).toBeGreaterThan(0)
+        for (const line of lines) {
+            expect(line).not.toContain("gcs://")
+            expect(line).not.toContain("bucket")
+        }
+    })
+
+    it("認証ポートが例外を投げても 500 の JSON を返す (認証呼び出しも try の内側にある)", async () => {
+        // 認証実装はセッション復号や warmup の失敗で素の例外を投げうる。
+        // authenticate を try の外に置くとこの穴が残り、プレーンテキストの 500 になる
+        const { config } = makeHandlersFixture({ attachment: visibleRow() })
+        const handlers = createDailyReportHandlers({
+            ...config,
+            authenticate: async () => {
+                throw new Error("session decode failed")
+            },
+        })
+        const res = await handlers.attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(500)
+        expect(res.headers.get("Content-Type")).toBe("application/json")
+        expect(await res.text()).not.toContain("session decode failed")
+    })
+
+    it("認証ポートが投げた Response (リダイレクト) は握り潰さず素通しする", async () => {
+        // リダイレクトは例外ではなく正常な制御フロー。500 に化けさせるとログイン導線が壊れる
+        const redirect = new Response(null, { status: 302, headers: { Location: "/auth/login" } })
+        const { config } = makeHandlersFixture({ attachment: visibleRow() })
+        const handlers = createDailyReportHandlers({
+            ...config,
+            authenticate: async () => {
+                throw redirect
+            },
+        })
+        await expect(handlers.attachment.loader(makeAttachmentArgs("A1"))).rejects.toBe(redirect)
+    })
+
+    it("読み取りポートが例外を投げても 500 の JSON を返し、Set-Cookie を落とさない", async () => {
+        // 例外を漏らすとフレームワークの最終防衛線でプレーンテキストの 500 になり、
+        // セッション延長の Set-Cookie も失われる
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), cookie: "session=abc" })
+        const handlers = createDailyReportHandlers({ ...config, readAttachment: vi.fn().mockRejectedValue(new Error("boom")) })
+        const res = await handlers.attachment.loader(makeAttachmentArgs("A1"))
+        expect(res.status).toBe(500)
+        expect(res.headers.get("Content-Type")).toBe("application/json")
+        expect(res.headers.get("Set-Cookie")).toBe("session=abc")
+        // 内部の例外文言を応答本文へ載せない
+        expect(await res.text()).not.toContain("boom")
+    })
+
+    it("GET のスロットは本文を読み切るまで保持し、読み切ったら解放する", async () => {
+        // 読み取り完了時点で解放すると、前の応答のバイト列がヒープに載ったまま次の読み取りが
+        // 始まるため「同時実行上限 × 上限バイト数」というヒープ見積りが成立しなくなる
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), attachmentConcurrency: 1 })
+        const handlers = createDailyReportHandlers(config)
+
+        const first = await handlers.attachment.loader(makeAttachmentArgs("A1"))
+        expect(first.status).toBe(200)
+        // 本文が未消費の間はスロットが空かない
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A2"))).status).toBe(503)
+
+        // 読み切るとスロットが返る
+        expect((await first.arrayBuffer()).byteLength).toBe(3)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A3"))).status).toBe(200)
+    })
+
+    it("本文をキャンセルした場合もスロットを解放する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), attachmentConcurrency: 1 })
+        const handlers = createDailyReportHandlers(config)
+        const first = await handlers.attachment.loader(makeAttachmentArgs("A1"))
+        await first.body?.cancel()
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A2"))).status).toBe(200)
+    })
+
+    it("HEAD は本文を持たないため即座にスロットを解放する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), attachmentConcurrency: 1 })
+        const handlers = createDailyReportHandlers(config)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A1", { method: "HEAD" }))).status).toBe(200)
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A2", { method: "HEAD" }))).status).toBe(200)
+    })
+
+    it("失敗時にも同時実行スロットを解放する", async () => {
+        const { config } = makeHandlersFixture({ attachment: visibleRow(), attachmentConcurrency: 1 })
+        const handlers = createDailyReportHandlers({
+            ...config,
+            readAttachment: vi
+                .fn()
+                .mockRejectedValueOnce(new Error("boom"))
+                .mockResolvedValue({ ok: true as const, bytes: threeBytes(), contentType: null }),
+        })
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A1"))).status).toBe(500)
+        // 1 回目で解放されていなければここが 503 になる
+        expect((await handlers.attachment.loader(makeAttachmentArgs("A2"))).status).toBe(200)
+    })
+})
+
+describe("純粋ヘルパー (第 2 層の防御を直接固定する)", () => {
+    // ミューテーションテストで判明: 配信経路だけを見ると sanitizeMediaType は到達不能なため、
+    // 撤去しても 28 件のテストが全て通ってしまう。第 2 層には第 2 層のゲートを与える。
+    it("sanitizeMediaType は CR/LF を含む値を拒否する", () => {
+        expect(sanitizeMediaType("text/plain\r\nX-Injected: 1")).toBeNull()
+        expect(sanitizeMediaType("text/plain\nX-Injected: 1")).toBeNull()
+    })
+
+    it("sanitizeMediaType は非 ASCII を含む値を拒否する", () => {
+        expect(sanitizeMediaType('application/pdf; name="あ"')).toBeNull()
+    })
+
+    it("sanitizeMediaType は MIME 型の形をしていない値を拒否する", () => {
+        expect(sanitizeMediaType("not-a-media-type")).toBeNull()
+        expect(sanitizeMediaType("")).toBeNull()
+        expect(sanitizeMediaType(null)).toBeNull()
+        expect(sanitizeMediaType(undefined)).toBeNull()
+    })
+
+    it("sanitizeMediaType は正当な値をそのまま通す", () => {
+        expect(sanitizeMediaType("image/png")).toBe("image/png")
+        expect(sanitizeMediaType("application/vnd.ms-excel")).toBe("application/vnd.ms-excel")
+        expect(sanitizeMediaType("text/plain; charset=utf-8")).toBe("text/plain; charset=utf-8")
+    })
+
+    it("encodeRfc8187 は encodeURIComponent が残す ' ( ) * を符号化する", () => {
+        // encodeURIComponent はこの 4 文字を残すが、いずれも RFC 8187 の attr-char ではない
+        expect(encodeURIComponent("a'b(c)d*e")).toBe("a'b(c)d*e")
+        expect(encodeRfc8187("a'b(c)d*e")).toBe("a%27b%28c%29d%2Ae")
+    })
+
+    it("encodeRfc8187 は日本語を UTF-8 パーセント符号化する", () => {
+        expect(encodeRfc8187("報告書.pdf")).toBe("%E5%A0%B1%E5%91%8A%E6%9B%B8.pdf")
+    })
+
+    it("asciiFallbackFileName は非 ASCII と引用符・バックスラッシュを置換する", () => {
+        expect(asciiFallbackFileName('報告書"x\\y.pdf')).toBe("____x_y.pdf")
+        expect(asciiFallbackFileName("plain.pdf")).toBe("plain.pdf")
+    })
+})