@aiquants/daily-report 0.6.2 → 0.8.0

package/src/server/handlers.ts

@@ -7,9 +7,11 @@
  * - sse.loader: Redis Streams ベースのリアルタイム更新 SSE エンドポイント
  */
 import { normalizeBusinessDateKey } from "../shared/business-date"
+import { type DailyReportIdsStreamChunkLine, type DailyReportIdsStreamCursor, findIdsStreamResumeIndex } from "../shared/ids-stream"
 import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
 import { dailyReportSseMessageSchema } from "../shared/sse-schema"
-import type { DailyReportAuthenticate, DailyReportEncodeUserId, DailyReportRedisProvider } from "./ports"
+import type { DailyReportItem } from "../shared/types"
+import type { DailyReportAttachmentFailure, DailyReportAuthenticate, DailyReportEncodeUserId, DailyReportIdCodec, DailyReportReadAttachment, DailyReportRedisProvider } from "./ports"
 import { jsonResponseWithETag } from "./response"
 import type { DailyReportService } from "./service"
 import type { DailyReportSseReader, StreamEntry } from "./sse-reader"
@@ -24,6 +26,421 @@ const jsonData = (payload: unknown, init?: { status?: number }): Response =>
         headers: { "Content-Type": "application/json" },
     })
 
+// ---------------- ids NDJSON ストリームの定数とヘルパー (純粋・モジュールスコープ) ----------------
+
+/**
+ * First-chunk size, tuned for time-to-first-render.
+ * 初回チャンクのアイテム数。最初の描画までの時間を優先して小さく保つ。
+ *
+ * 一覧の可視行 + オーバースキャンを一度に満たせる件数であればよい。
+ */
+const IDS_STREAM_FIRST_CHUNK_SIZE = 200
+
+/**
+ * 2 チャンク目以降のアイテム数。1 アイテムが数十バイト (id/日付/種別のみ) と軽いため
+ * 大きめに運ぶ。実データは 20 万件超に達するため、小さすぎると行数 (= pull 往復と
+ * クライアント側 publish 回数) が肥大する (4000 件 ≈ 240 KB/行、20 万件で約 50 行)。
+ */
+const IDS_STREAM_NEXT_CHUNK_SIZE = 4000
+
+/**
+ * Sanitized message for mid-stream failures (no internal details).
+ * ストリーム送出中の失敗をクライアントへ伝える定型文 (内部情報は載せない)。
+ */
+const IDS_STREAM_ERROR_CLIENT_MESSAGE = "stream interrupted by server error"
+
+/** 再開カーソルの営業日として受け付ける唯一の形式 (正規化済み YYYY-MM-DD)。 */
+const IDS_STREAM_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * Parses and validates resume-cursor query params (fail-closed).
+ * 再開カーソルのクエリパラメータを検証付きで解釈する処理 (不正は fail-closed)。
+ *
+ * - `cursor_report_hub_id` 単独 = 「営業日なし領域」のカーソル (businessDate: null)。
+ * - `cursor_business_date` は `cursor_report_hub_id` 無しでは意味を持たないため 400。
+ *
+ * @param url Request URL. リクエスト URL。
+ * @returns Cursor (null = 先頭から) か、検証失敗の印。
+ */
+const parseIdsStreamCursor = (url: URL): { cursor: DailyReportIdsStreamCursor | null } | { invalid: true } => {
+    const rawId = url.searchParams.get("cursor_report_hub_id")
+    const rawDate = url.searchParams.get("cursor_business_date")
+
+    if (rawId === null) {
+        // 営業日だけのカーソルは並び順上の位置を決められない
+        return rawDate === null ? { cursor: null } : { invalid: true }
+    }
+
+    const reportHubId = Number.parseInt(rawId, 10)
+    if (!Number.isSafeInteger(reportHubId) || String(reportHubId) !== rawId || reportHubId <= 0) {
+        return { invalid: true }
+    }
+
+    if (rawDate === null) {
+        return { cursor: { businessDate: null, reportHubId } }
+    }
+    if (!IDS_STREAM_DATE_PATTERN.test(rawDate)) {
+        return { invalid: true }
+    }
+    return { cursor: { businessDate: rawDate, reportHubId } }
+}
+
+/**
+ * Emits a finalized id array as chunked NDJSON lines from a resume position.
+ * 確定済み ID 配列を再開位置からチャンク行として送出するジェネレーター。
+ *
+ * `total` は最初に yield する行へ載せる (= 接続内で全量が確定した最初の行。
+ * キャッシュヒットの新規接続と再開接続では先頭行、高速先頭ページ経路では 2 行目)。
+ *
+ * @param items Stream-ordered full array. ストリーム順の全量配列。
+ * @param resumeKey Resume position (null = 先頭から)。
+ * @param firstChunkSize このジェネレーターの最初のチャンクサイズ。
+ */
+async function* streamLinesFromFullArray(items: DailyReportItem[], resumeKey: DailyReportIdsStreamCursor | null, firstChunkSize = IDS_STREAM_FIRST_CHUNK_SIZE): AsyncGenerator<DailyReportIdsStreamChunkLine> {
+    let position = resumeKey ? findIdsStreamResumeIndex(items, resumeKey) : 0
+    let isFirstYield = true
+    while (true) {
+        const chunkItems = items.slice(position, position + (isFirstYield ? firstChunkSize : IDS_STREAM_NEXT_CHUNK_SIZE))
+        position += chunkItems.length
+        const isLast = position >= items.length
+        const lastItem = chunkItems[chunkItems.length - 1]
+        yield {
+            items: chunkItems,
+            nextCursor: isLast || !lastItem ? null : { businessDate: lastItem.businessDate, reportHubId: lastItem.reportHubId },
+            isLast,
+            ...(isFirstYield ? { total: items.length } : {}),
+        }
+        isFirstYield = false
+        if (isLast) return
+    }
+}
+
+/**
+ * Wraps a line iterator into a pull-based NDJSON streaming Response.
+ * 行イテレーターを pull 駆動の NDJSON ストリーミング Response へ包む処理。
+ *
+ * - 切断検知時はイテレーターを畳んで (`return()`) DB 待ちを解放し、close する
+ *   (素の return は desiredSize > 0 のまま pull が再帰する)。
+ * - イテレーターの throw は内部情報を含まない定型エラー行 + 正常クローズへ倒す
+ *   (クライアントは「isLast 無し終端」をカーソル再開のシグナルとして扱う)。
+ */
+const buildIdsStreamResponse = (cookie: string | null, lines: AsyncGenerator<DailyReportIdsStreamChunkLine>, request: Request, logger: DailyReportLogger): Response => {
+    const encoder = new TextEncoder()
+    // cancel() の lines.return() は「pull が DB 待ちの next() を保留中」だと先取りできない。
+    // 待ちが明けた後の enqueue が閉じたストリームへ落ちて catch に入るため、切断は
+    // フラグで決定的に識別し、通常イベントとして静かに畳む (ERROR ログにしない —
+    // 全量クエリ中の離脱は日常イベントで、本物の送出失敗が雑音に埋もれる)
+    let cancelled = false
+    const stream = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+            if (cancelled || request.signal.aborted) {
+                await lines.return(undefined).catch(() => {})
+                try {
+                    controller.close()
+                } catch {
+                    // cancel 済みコントローラーの close は失敗してよい
+                }
+                return
+            }
+            try {
+                const { value, done } = await lines.next()
+                if (done) {
+                    controller.close()
+                    return
+                }
+                // 保留中の next() の間に切断された場合はここで検知して静かに終える
+                if (cancelled || request.signal.aborted) {
+                    await lines.return(undefined).catch(() => {})
+                    try {
+                        controller.close()
+                    } catch {
+                        // cancel 済みコントローラーの close は失敗してよい
+                    }
+                    return
+                }
+                controller.enqueue(encoder.encode(`${JSON.stringify(value)}\n`))
+            } catch (error) {
+                if (cancelled || request.signal.aborted) {
+                    // 切断起因の enqueue/close 失敗はエラーではない
+                    return
+                }
+                logger.error(`ids-stream emission failed: ${error instanceof Error ? error.message : String(error)}`)
+                try {
+                    controller.enqueue(encoder.encode(`${JSON.stringify({ error: IDS_STREAM_ERROR_CLIENT_MESSAGE })}\n`))
+                    controller.close()
+                } catch {
+                    // 既に切断済みなら何もできない
+                }
+            }
+        },
+        cancel() {
+            cancelled = true
+            void lines.return(undefined).catch(() => {})
+        },
+    })
+
+    const headers = new Headers({
+        "Content-Type": "application/x-ndjson; charset=utf-8",
+        // no-transform: compression ミドルウェア/中間プロキシによるバッファリングを禁止する (SSE と同じ理由)
+        "Cache-Control": "private, no-cache, no-transform",
+        "X-Content-Type-Options": "nosniff",
+    })
+    if (cookie) {
+        headers.append("Set-Cookie", cookie)
+    }
+    return new Response(stream, { status: 200, headers })
+}
+
+// ---------------- 添付配信の定数とヘルパー (純粋・モジュールスコープ) ----------------
+
+/** 添付 1 件あたりの既定上限。サービス側のワイヤ上限 (既定 64 MiB) より必ず低く保つ。 */
+const DEFAULT_ATTACHMENT_MAX_BYTES = 32 * 1024 * 1024
+
+/**
+ * Default per-user rate limit (calls per minute), enforced per process.
+ * ユーザー単位の既定レート上限 (1 分あたり)。ただし**プロセス単位**で計上する。
+ *
+ * バケットはハンドラーのクロージャに置く素の `Map` であり、プロセス間で共有されない。
+ * 消費アプリが Node Cluster 等で複数ワーカーを起動する場合、コンテナ全体の実効上限は
+ * この値のワーカー数倍になる。全体で厳密に効かせたいなら共有ストア (Redis 等) が要る。
+ */
+const DEFAULT_ATTACHMENT_RATE_LIMIT_PER_MINUTE = 60
+
+/**
+ * Default simultaneous-read limit, enforced per process.
+ * 既定の同時実行上限。**プロセス単位**で計上する。
+ *
+ * 1 リクエストが上限バイト数をヒープへ載せるため小さく保つ。ヒープ見積りは
+ * 「この値 × `attachmentMaxBytes` × ワーカー数」であり、ワーカー数を掛け忘れると
+ * コンテナのメモリ上限を実際の数倍で見誤る。消費アプリはワーカー数を織り込んだ値を
+ * `attachmentConcurrency` で明示注入すること。
+ *
+ * スロットは**本文をクライアントへ送出し終えるまで**保持する。読み取り完了時点で
+ * 解放すると、前の応答のバイト列がヒープに載ったまま次の読み取りが始まるため、
+ * 上の見積りが成立しなくなる (実際の同時保持数は無制限になる)。
+ */
+const DEFAULT_ATTACHMENT_CONCURRENCY = 4
+
+/**
+ * Backstop for releasing a concurrency slot when the client never drains the body.
+ * クライアントが本文を読み切らない場合に同時実行スロットを解放するバックストップ。
+ *
+ * スロットを送出完了まで保持する以上、接続を張ったまま読み止めたクライアントが
+ * スロットを永久に占有できてしまう。これは締め切りではなく枯渇防止の保険であり、
+ * 超過しても応答は中断しない (単にゲートの会計上、保持されていない扱いにするだけ)。
+ */
+const ATTACHMENT_BODY_FLUSH_TIMEOUT_MS = 120_000
+
+/** レート制限テーブルの上限件数。無制限 Map はプロセス寿命の間だけ単調増加するリークになる。 */
+const RATE_LIMITER_MAX_ENTRIES = 1024
+
+/** レート上限超過時に提示する再試行間隔 (秒)。 */
+const RATE_LIMIT_RETRY_AFTER_SECONDS = 60
+
+/** 同時実行上限に達したときに提示する再試行間隔 (秒)。 */
+const CONCURRENCY_RETRY_AFTER_SECONDS = 5
+
+/**
+ * Media types allowed to render inline in the browser.
+ * ブラウザーへインライン表示してよい media type。
+ *
+ * これ以外は必ず添付ダウンロードにし、Content-Type も `application/octet-stream` へ落とす。
+ * `file_type` は外部システム由来の未検証値であり、`text/html` や `image/svg+xml` を
+ * 自オリジンでインライン配信するとセッション Cookie を持つ文脈でスクリプトが動く。
+ * `X-Content-Type-Options: nosniff` は「宣言型から外れた推測」を止めるだけで、
+ * 宣言された型の実行は止めない。
+ */
+const INLINE_SAFE_MEDIA_TYPES: ReadonlySet<string> = new Set(["image/png", "image/jpeg", "image/gif", "image/webp", "application/pdf", "text/plain"])
+
+/** ヘッダー値として安全で、かつ MIME 型の形をしている値だけを通す。 */
+const HEADER_SAFE_PATTERN = /^[\x20-\x7E]+$/
+const MEDIA_TYPE_PATTERN = /^[\w.+-]+\/[\w.+-]+/
+
+/**
+ * Accepts a media type only when it is header-safe and well-formed.
+ * ヘッダー安全かつ MIME 型の形をしている場合のみ採用する処理。
+ *
+ * CR/LF や 0x00-0xFF 外の文字が混ざった値を `new Headers()` へ渡すと TypeError になり、
+ * 認可済みのダウンロードが 500 になる。
+ *
+ * **これは第 2 層である。** 現在の配信経路では、注入値はインライン許可リストに完全一致しないため
+ * 必ず `application/octet-stream` へ落ち、ヘッダーには到達しない。つまり本関数を外しても
+ * 現状の挙動は変わらない (ミューテーションテストで確認済み)。
+ * 許可判定を前方一致や「DB の型を信じる」形へ変えた瞬間に効き始める防御なので、
+ * 到達不能なまま放置せず **直接の単体テストで固定する**目的でエクスポートしている。
+ *
+ * @param value Candidate media type. 候補となる media type。
+ * @returns The value when acceptable, otherwise null. 採用可なら値、それ以外は null。
+ */
+export const sanitizeMediaType = (value: string | null | undefined): string | null => (value && HEADER_SAFE_PATTERN.test(value) && MEDIA_TYPE_PATTERN.test(value) ? value : null)
+
+/**
+ * Percent-encodes a file name for the RFC 8187 `filename*` parameter.
+ * RFC 8187 の `filename*` 用にファイル名をパーセントエンコードする処理。
+ *
+ * `encodeURIComponent` は `'` `(` `)` `*` を残すが、いずれも RFC 8187 の attr-char ではない。
+ *
+ * @param name Raw file name. 生のファイル名。
+ * @returns Encoded value. エンコード済みの値。
+ */
+export const encodeRfc8187 = (name: string): string => encodeURIComponent(name).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+
+/**
+ * Builds the ASCII fallback used by the plain `filename` parameter.
+ * 素の `filename` パラメータ用の ASCII フォールバックを組み立てる処理。
+ *
+ * @param name Raw file name. 生のファイル名。
+ * @returns ASCII-only, quote-free name. ASCII のみで引用符を含まない名前。
+ */
+export const asciiFallbackFileName = (name: string): string => name.replace(/[^\x20-\x7E]/g, "_").replace(/["\\]/g, "_")
+
+/**
+ * Maps a storage read failure onto the HTTP status the endpoint returns.
+ * ストレージ読み取りの失敗種別を、エンドポイントが返す HTTP ステータスへ写像する処理。
+ *
+ * `not_found` と `denied` はどちらも 404 にする。認可判定は既に SQL 側で完了しているため
+ * 横断的な情報漏洩は無いが、実体の有無を 403/404 で区別すると存在オラクルになる。
+ *
+ * @param reason Failure kind reported by the port. ポートが報告した失敗種別。
+ * @returns HTTP status code. HTTP ステータスコード。
+ */
+const attachmentFailureToStatus = (reason: DailyReportAttachmentFailure): number => {
+    switch (reason) {
+        case "not_found":
+        case "denied":
+        case "invalid_path":
+            return 404
+        case "too_large":
+            return 413
+        default:
+            return 502
+    }
+}
+
+/**
+ * Client-facing messages per failure status.
+ * 失敗ステータスごとのクライアント向けメッセージ。
+ *
+ * 404 は「存在しない」「認可されない」「実体が消えた」の合流点なので、
+ * どの経路から来ても同一の文面にする (差分が存在オラクルになるため)。
+ */
+const ATTACHMENT_FAILURE_MESSAGES: Readonly<Record<number, string>> = {
+    404: "Attachment not found",
+    413: "Attachment too large",
+    502: "Attachment storage unavailable",
+}
+
+/** レート制限 1 ユーザー分の状態。 */
+type RateBucket = { tokens: number; lastRefillMs: number }
+
+/**
+ * Creates a bounded per-user token-bucket rate limiter (process-local).
+ * ユーザー単位のトークンバケット方式レート制限を、件数上限付きで生成する処理 (プロセス内限定)。
+ *
+ * 上限を設ける理由: 素の `Map` で保持するとプロセス寿命の間だけ単調増加し、
+ * 「サーバー側の状態は上限を持つ」という設計方針 (SqlResultCache の >500 GC) に反する。
+ * 上限到達時は挿入順が最も古いエントリから落とす。
+ *
+ * 状態はプロセス内に閉じるため、マルチワーカー配備では実効上限がワーカー数倍になる
+ * (`DEFAULT_ATTACHMENT_RATE_LIMIT_PER_MINUTE` 参照)。
+ *
+ * @param limitPerMinute Allowed calls per minute. 1 分あたりの許可回数。
+ * @returns A function that consumes one token and reports whether it was allowed. トークンを 1 つ消費し可否を返す関数。
+ */
+const createRateLimiter = (limitPerMinute: number) => {
+    const buckets = new Map<number, RateBucket>()
+    return (userId: number, nowMs: number): boolean => {
+        const existing = buckets.get(userId)
+        // アクセスのたびに再挿入して LRU 順序にする (Map は挿入順を保つ)
+        if (existing) buckets.delete(userId)
+
+        const bucket = existing ?? { tokens: limitPerMinute, lastRefillMs: nowMs }
+        const elapsedMs = Math.max(0, nowMs - bucket.lastRefillMs)
+        if (elapsedMs > 0) {
+            bucket.tokens = Math.min(limitPerMinute, bucket.tokens + (elapsedMs * limitPerMinute) / 60_000)
+            bucket.lastRefillMs = nowMs
+        }
+
+        const allowed = bucket.tokens >= 1
+        if (allowed) bucket.tokens -= 1
+
+        buckets.set(userId, bucket)
+        while (buckets.size > RATE_LIMITER_MAX_ENTRIES) {
+            const oldest = buckets.keys().next()
+            if (oldest.done) break
+            buckets.delete(oldest.value)
+        }
+        return allowed
+    }
+}
+
+/**
+ * Creates a fail-fast concurrency gate (no queueing, process-local).
+ * 待ち行列を持たない即時失敗型の同時実行ゲートを生成する処理 (プロセス内限定)。
+ *
+ * 待たせるとリクエストを掴んだまま滞留するだけなので、上限超過は即座に 503 を返す。
+ * カウンタはプロセス内に閉じるため、マルチワーカー配備ではコンテナ全体の同時読み取り数が
+ * 上限のワーカー数倍になる (`DEFAULT_ATTACHMENT_CONCURRENCY` 参照)。
+ *
+ * @param limit Maximum simultaneous holders. 同時保持数の上限。
+ * @returns Acquire/release pair. 取得と解放の組。
+ */
+const createConcurrencyGate = (limit: number) => {
+    let active = 0
+    return {
+        tryAcquire: (): boolean => {
+            if (active >= limit) return false
+            active += 1
+            return true
+        },
+        release: (): void => {
+            if (active > 0) active -= 1
+        },
+    }
+}
+
+/**
+ * Streams already-materialized bytes and releases the held slot once the body is drained.
+ * materialize 済みのバイト列をストリームとして送出し、送出完了時に保持中のスロットを解放する処理。
+ *
+ * 読み取り完了時点で解放してはならない。その時点でバイト列はまだヒープ上にあり、
+ * 応答が流し切られるまで参照が保持されるため、「同時実行上限 × 上限バイト数」という
+ * ヒープ見積りが成立しなくなる。ここで送出完了まで保持することで見積りを実際に成立させる。
+ *
+ * 解放は必ず 1 回だけ行う (正常終了・キャンセル・バックストップのいずれか最初の 1 回)。
+ *
+ * @param bytes Body bytes to send. 送出する本文のバイト列。
+ * @param release Idempotent slot release. 冪等なスロット解放関数。
+ * @param timeoutMs Backstop before force-releasing. 強制解放までのバックストップ時間。
+ * @returns A stream that emits the bytes once. バイト列を 1 度だけ流すストリーム。
+ */
+const streamAndRelease = (bytes: Uint8Array<ArrayBuffer>, release: () => void, timeoutMs: number): ReadableStream<Uint8Array> => {
+    const timer: ReturnType<typeof setTimeout> = setTimeout(release, timeoutMs)
+    // タイマーがプロセス終了を待たせないようにする (Node 以外では unref を持たない)
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+    const finish = () => {
+        clearTimeout(timer)
+        release()
+    }
+
+    let sent = false
+    return new ReadableStream<Uint8Array>({
+        pull(controller) {
+            // 1 回目の pull で本文を積み、消費された後の 2 回目の pull で閉じて解放する
+            if (sent) {
+                controller.close()
+                finish()
+                return
+            }
+            sent = true
+            controller.enqueue(bytes)
+        },
+        cancel() {
+            finish()
+        },
+    })
+}
+
 export type DailyReportHandlersConfig = {
     /** リクエスト認証ポート。 */
     authenticate: DailyReportAuthenticate
@@ -31,6 +448,19 @@ export type DailyReportHandlersConfig = {
     service: DailyReportService
     /** 内部数値 ID の難読化ポート。 */
     encodeUserId: DailyReportEncodeUserId
+    /**
+     * 添付 ID の難読化コーデック。未注入なら添付エンドポイントは常に 404。
+     * ユーザー ID 用とは別インスタンスを渡すこと (ID 空間の分離)。
+     */
+    attachmentIdCodec?: DailyReportIdCodec
+    /** 添付ファイル読み取りポート。未注入なら添付エンドポイントは常に 404。 */
+    readAttachment?: DailyReportReadAttachment
+    /** 添付ファイルの最大バイト数 (既定 32 MiB)。サービス側のワイヤ上限より低く保つこと。 */
+    attachmentMaxBytes?: number
+    /** 添付エンドポイントの 1 分あたり呼び出し上限 (ユーザー単位・既定 60)。 */
+    attachmentRateLimitPerMinute?: number
+    /** 添付読み取りの同時実行上限 (プロセス単位・既定 4)。 */
+    attachmentConcurrency?: number
     /** SSE 用 redis プロバイダー (catch-up の xRange / xRevRange に使用)。 */
     redis?: DailyReportRedisProvider
     /** SSE Fan-Out 共有リーダー。 */
@@ -52,6 +482,12 @@ export function createDailyReportHandlers(config: DailyReportHandlersConfig) {
     const loginRedirectPath = config.loginRedirectPath ?? "/auth/login"
     const apiLogger = config.logger ?? createLogger(LogLevel.ERROR, "[DailyReportAPI]")
     const sseLogger = config.logger ?? createLogger(LogLevel.INFO, "[DailyReportSSE]")
+    const attachmentLogger = config.logger ?? createLogger(LogLevel.INFO, "[DailyReportAttachment]")
+
+    // 添付配信のプロセス内状態。ファクトリ 1 インスタンスにつき 1 組。
+    const attachmentMaxBytes = config.attachmentMaxBytes ?? DEFAULT_ATTACHMENT_MAX_BYTES
+    const consumeAttachmentRateToken = createRateLimiter(config.attachmentRateLimitPerMinute ?? DEFAULT_ATTACHMENT_RATE_LIMIT_PER_MINUTE)
+    const attachmentGate = createConcurrencyGate(config.attachmentConcurrency ?? DEFAULT_ATTACHMENT_CONCURRENCY)
 
     // ---------------- index (画面ルート) ----------------
 
@@ -101,13 +537,86 @@ export function createDailyReportHandlers(config: DailyReportHandlersConfig) {
             return jsonResponseWithETag(request, cookie, { businessDate: normalizedBusinessDate, reports }, 200)
         },
         /**
-         * Retrieves a list of all daily report IDs.
-         * 全ての日報 ID の一覧を取得する。
+         * Streams the full daily report id list as NDJSON chunks.
+         * 日報 ID 一覧全件を NDJSON チャンクとして逐次配信する。
+         *
+         * 全量クエリ (`SqlResultCache` の TTL / Redis epoch / in-flight コアレッシングを
+         * 素通しで維持) は常に即時に開始する。全量確定を待ってから送出するのは再開接続のみで、
+         * その場合の DB エラーはストリーム開始前に throw されて apiLoader の catch が
+         * 500 JSON を返す。新規接続はキャッシュ無しの TOP 200 高速先頭ページと競争させ、
+         * キャッシュミス時は全量確定前に最初のチャンクを送出する (最初の描画までの時間が
+         * 全体データ量に依存しない)。キャッシュヒット時は全量が即勝ちし、従来どおり
+         * 確定済み配列のメモリスライス送出になる。
          */
-        ids: async (url, cookie, request, user) => {
+        "ids-stream": async (url, cookie, request, user) => {
+            const parsed = parseIdsStreamCursor(url)
+            if ("invalid" in parsed) {
+                return jsonResponseWithETag(request, cookie, { error: { message: "Invalid cursor" } }, 400)
+            }
             const forceRefresh = url.searchParams.get("forceRefresh") === "true"
-            const dailyReportIds = await service.getDailyReportIdsByExternalId(user.id, { forceRefresh })
-            return jsonResponseWithETag(request, cookie, { ids: dailyReportIds }, 200)
+
+            // 全量 (SqlResultCache / epoch / コアレッシング維持) は常に即時に走らせ始める
+            const fullArrayPromise = service.getDailyReportIdsByExternalId(user.id, { forceRefresh })
+            // 拒否はイテレーターの await 側で扱う (ここで未処理拒否警告を出さない)
+            fullArrayPromise.catch(() => {})
+
+            if (parsed.cursor) {
+                // 再開接続: クライアントは高速先頭を受信済みなので全量確定を待つ (エラーは 500)
+                return buildIdsStreamResponse(cookie, streamLinesFromFullArray(await fullArrayPromise, parsed.cursor), request, apiLogger)
+            }
+
+            /**
+             * 新規接続: 「高速先頭ページ (TOP n・キャッシュ無し)」と「全量 (キャッシュ経由)」を
+             * 競争させ、先に確定した方で最初のチャンクを出す。キャッシュヒット時は全量が即勝ち
+             * (従来どおり先頭行に total)。キャッシュミス時は先頭ページが先に届き、最初の描画は
+             * 全量クエリの確定を待たない。total は全量確定後の最初の行に載る。
+             */
+            // キャッシュヒット時もこの TOP 200 クエリは走って結果が捨てられる (二重クエリ)。
+            // インデックス順の部分走査で ms 級と実測見積もりされており、ヒット判定のための
+            // キャッシュ同期 peek API を足す複雑さに見合わないため意図的に許容する
+            const firstPagePromise = service.getDailyReportIdsFirstPageByExternalId(user.id, IDS_STREAM_FIRST_CHUNK_SIZE)
+            firstPagePromise.catch(() => {})
+
+            const lineIterator = (async function* (): AsyncGenerator<DailyReportIdsStreamChunkLine> {
+                const winner = await Promise.race([
+                    fullArrayPromise.then(
+                        (items) => ({ kind: "full" as const, items }),
+                        (error) => ({ kind: "full-error" as const, error }),
+                    ),
+                    firstPagePromise.then(
+                        (items) => ({ kind: "page" as const, items }),
+                        () => ({ kind: "page-error" as const }),
+                    ),
+                ])
+
+                let resumeKey: DailyReportIdsStreamCursor | null = null
+                let fullItems: DailyReportItem[] | null = null
+
+                if (winner.kind === "full") {
+                    fullItems = winner.items
+                } else if (winner.kind === "page" || winner.kind === "full-error") {
+                    // 全量が先に死んでいても先頭ページが生きていれば、まずそれを届ける
+                    const pageItems = winner.kind === "page" ? winner.items : await firstPagePromise
+                    if (pageItems.length < IDS_STREAM_FIRST_CHUNK_SIZE) {
+                        // 先頭ページが上限未満 = データセット全量。全量クエリを待たずに完結する
+                        yield { items: pageItems, nextCursor: null, isLast: true, total: pageItems.length }
+                        return
+                    }
+                    const lastItem = pageItems[pageItems.length - 1]
+                    resumeKey = { businessDate: lastItem.businessDate, reportHubId: lastItem.reportHubId }
+                    // total は未知 (全量確定後の行に載せる)
+                    yield { items: pageItems, nextCursor: resumeKey, isLast: false }
+                }
+                // page-error は全量へフォールバック。full-error は上の分岐でページを出してから、ここで throw する
+                if (fullItems === null) {
+                    fullItems = await fullArrayPromise
+                }
+                // 高速先頭ページ経路 (resumeKey あり) はクライアントが既に 200 件を描画済み
+                // なので、続きは大きいチャンクで運ぶ。キャッシュヒット経路は従来どおり 200 件先頭
+                yield* streamLinesFromFullArray(fullItems, resumeKey, resumeKey ? IDS_STREAM_NEXT_CHUNK_SIZE : IDS_STREAM_FIRST_CHUNK_SIZE)
+            })()
+
+            return buildIdsStreamResponse(cookie, lineIterator, request, apiLogger)
         },
         /**
          * Retrieves details for a specific daily report.
@@ -540,9 +1049,165 @@ export function createDailyReportHandlers(config: DailyReportHandlersConfig) {
         })
     }
 
+    // ---------------- attachment (認可済みバイト配信) ----------------
+
+    /**
+     * Streams an authorized attachment's bytes to the client.
+     * 認可済みの添付ファイルをバイト列としてクライアントへ返すローダー。
+     *
+     * 認可は `service.getAttachmentForUser` の SQL 述語で完結させる。ストレージ側の
+     * 資格情報はサービス共通のものであり、利用者間の分離を一切提供しない。
+     * したがってこの述語が唯一の認可境界であり、ここに欠陥があれば全テナント横断の読み取りになる。
+     *
+     * 「存在しない」と「認可されない」は区別せず 404 にする (存在オラクル回避)。
+     *
+     * 本体は必ず try/catch で包む。ここで漏らした例外はフレームワークの最終防衛線に落ち、
+     * JSON ではないプレーンテキストの 500 になるうえ `Set-Cookie` (セッション延長) も失われる。
+     * **認証ポートの呼び出しも try の内側**に置くこと。認証実装はセッション復号や warmup の
+     * 失敗で素の例外を投げうるため、外に置くと同じ穴が残る。ただしリダイレクトは `Response` を
+     * throw する正常な制御フローなので、catch では素通しする。
+     */
+    const attachmentLoader = async ({ request, params }: LoaderArgs) => {
+        let sanitizedCookie: string | null = null
+
+        /** エラー応答。`Set-Cookie` はすべての分岐で伝播させる。 */
+        const fail = (status: number, message: string, retryAfterSeconds?: number): Response => {
+            const headers = new Headers({ "Content-Type": "application/json" })
+            if (retryAfterSeconds !== undefined) headers.set("Retry-After", String(retryAfterSeconds))
+            if (sanitizedCookie) headers.append("Set-Cookie", sanitizedCookie)
+            return new Response(JSON.stringify({ error: { message } }), { status, headers })
+        }
+
+        try {
+            const { user, cookie } = await authenticate(request, { failureRedirect: null })
+            sanitizedCookie = cookie ?? null
+
+            if (!user) return fail(401, "Unauthorized")
+            if (request.method !== "GET" && request.method !== "HEAD") return fail(405, "Method not allowed")
+
+            const codec = config.attachmentIdCodec
+            const readAttachment = config.readAttachment
+            // ポート未注入は「この配備に添付機能が無い」であり、認可失敗と区別しない
+            if (!(codec && readAttachment)) return fail(404, "Attachment not found")
+
+            const token = params.token ?? ""
+            const attachmentId = codec.decode(token)
+            // `Number.isSafeInteger` であること。可逆難読化は入力トークンの正準性を検証しないため、
+            // 正規トークンと同じ長さの入力から 2^53 を超える値が復号されうる。それを SQL パラメータへ
+            // 渡すとドライバーの範囲検証が TypeError を投げ、400 のはずが 500 になる。
+            if (attachmentId === null || !Number.isSafeInteger(attachmentId) || attachmentId <= 0) {
+                return fail(400, "Invalid attachment token")
+            }
+
+            const internalUserId = await service.getUserIdByExternalId(user.id)
+            if (!internalUserId) return fail(403, "Forbidden")
+
+            // レート制限。トークンは列挙可能なので、これが実効的な唯一の緩和策
+            if (!consumeAttachmentRateToken(internalUserId, Date.now())) {
+                attachmentLogger.error(`429 attachment=${attachmentId} viewer=${internalUserId} reason=rate_limit`)
+                return fail(429, "Too many requests", RATE_LIMIT_RETRY_AFTER_SECONDS)
+            }
+
+            // 認可判定 (SQL 側で完結)。null は「存在しない」「認可されない」「親が論理削除済み」の合流
+            const attachment = await service.getAttachmentForUser(attachmentId, internalUserId)
+            if (!attachment) {
+                attachmentLogger.error(`404 attachment=${attachmentId} viewer=${internalUserId} reason=not_visible`)
+                return fail(404, "Attachment not found")
+            }
+
+            // DB が既知サイズを持つ場合は読み取り前に弾く (サイズを報告しない取込元の行はここを通過する)
+            if (attachment.fileSize != null && attachment.fileSize > attachmentMaxBytes) {
+                attachmentLogger.error(`413 attachment=${attachmentId} viewer=${internalUserId} reason=db_size`)
+                return fail(413, "Attachment too large")
+            }
+
+            if (!attachmentGate.tryAcquire()) {
+                attachmentLogger.error(`503 attachment=${attachmentId} viewer=${internalUserId} reason=concurrency`)
+                return fail(503, "Too many concurrent downloads", CONCURRENCY_RETRY_AFTER_SECONDS)
+            }
+
+            // スロットの解放は冪等にする。早期 return・例外・送出完了のどの経路からでも
+            // ちょうど 1 回だけ返す必要がある
+            let gateReleased = false
+            const releaseGate = () => {
+                if (gateReleased) return
+                gateReleased = true
+                attachmentGate.release()
+            }
+            // 本文の送出完了まで保持する経路に入ったかどうか (入った場合のみ finally での解放を見送る)
+            let releaseDeferredToStream = false
+
+            try {
+                const isHead = request.method === "HEAD"
+                const result = await readAttachment(attachment.filePath, { maxBytes: attachmentMaxBytes, head: isHead, principal: encodeUserId(internalUserId) })
+
+                if (!result.ok) {
+                    const status = attachmentFailureToStatus(result.reason)
+                    // 実体消失は次回描画へ反映する。記録の失敗は配信結果に影響させない
+                    // (await しないので、拒否を捕まえないと未処理 Promise 拒否になる)
+                    if (result.reason === "not_found") {
+                        void service.markAttachmentMissing(attachmentId).catch((error: unknown) => {
+                            attachmentLogger.error(`markAttachmentMissing failed attachment=${attachmentId} message=${error instanceof Error ? error.message : "unknown"}`)
+                        })
+                    }
+                    // file_path / URI は絶対にログへ出さない (内部パス非露出の方針と整合させる)
+                    attachmentLogger.error(`${status} attachment=${attachmentId} viewer=${internalUserId} reason=${result.reason} code=${result.code ?? "-"}`)
+                    return fail(status, ATTACHMENT_FAILURE_MESSAGES[status] ?? "Attachment storage unavailable")
+                }
+
+                // インライン許可リスト外は宣言型ごと octet-stream へ落とす。構文検証だけでは
+                // text/html や image/svg+xml の自オリジン実行を止められない
+                const declared = sanitizeMediaType(attachment.fileType) ?? sanitizeMediaType(result.contentType) ?? "application/octet-stream"
+                const inlineSafe = INLINE_SAFE_MEDIA_TYPES.has(declared)
+                const wantsDownload = new URL(request.url).searchParams.get("download") === "1"
+                const contentType = inlineSafe ? declared : "application/octet-stream"
+                const disposition = inlineSafe && !wantsDownload ? "inline" : "attachment"
+
+                // HEAD は本体を読まないので `bytes` が空になる。RFC 9110 §9.3.2 が要求する
+                // 「GET と同じ Content-Length」を満たすため、ポートが申告した実サイズを優先する
+                const contentLength = result.size ?? result.bytes.byteLength
+                const headers = new Headers({
+                    "Content-Type": contentType,
+                    "Content-Length": String(contentLength),
+                    "Content-Disposition": `${disposition}; filename="${asciiFallbackFileName(attachment.fileName)}"; filename*=UTF-8''${encodeRfc8187(attachment.fileName)}`,
+                    "Cache-Control": "private, no-store",
+                    "X-Content-Type-Options": "nosniff",
+                    "Content-Security-Policy": "default-src 'none'; sandbox",
+                    "X-Frame-Options": "SAMEORIGIN",
+                })
+                if (sanitizedCookie) headers.append("Set-Cookie", sanitizedCookie)
+
+                // 実体を確認できたので消失記録を解除する。これが唯一の自動回復経路であり、
+                // 片方向のままだと一時障害で立った absent を利用者が自力で戻せない
+                // (UI は absent の添付にリンクを描画しないため再取得の手段が消える)
+                void service.markAttachmentPresent(attachmentId).catch((error: unknown) => {
+                    attachmentLogger.error(`markAttachmentPresent failed attachment=${attachmentId} message=${error instanceof Error ? error.message : "unknown"}`)
+                })
+
+                attachmentLogger.info(`200 attachment=${attachmentId} viewer=${internalUserId} type=${contentType} disposition=${disposition} bytes=${contentLength}`)
+                // HEAD は本文を持たないので即座に解放する。GET は送出完了まで保持し、
+                // 「同時実行上限 × 上限バイト数」というヒープ見積りを実際に成立させる
+                if (isHead) {
+                    return new Response(null, { status: 200, headers })
+                }
+                releaseDeferredToStream = true
+                return new Response(streamAndRelease(result.bytes, releaseGate, ATTACHMENT_BODY_FLUSH_TIMEOUT_MS), { status: 200, headers })
+            } finally {
+                // 送出へ引き渡した場合を除き、早期 return でも例外でも必ずここで返す
+                if (!releaseDeferredToStream) releaseGate()
+            }
+        } catch (error) {
+            // 認証ポートはリダイレクトを Response として throw する。これは正常な制御フローなので素通しする
+            if (error instanceof Response) throw error
+            attachmentLogger.error(`500 attachment=? viewer=? reason=unexpected message=${error instanceof Error ? error.message : "unknown"}`)
+            return fail(500, "Attachment request failed")
+        }
+    }
+
     return {
         index: { loader: indexLoader },
         api: { loader: apiLoader, action: apiAction },
         sse: { loader: sseLoader },
+        attachment: { loader: attachmentLoader },
     }
 }