@aiquants/daily-report 0.6.2 → 0.7.0

package/src/server/handlers.ts

@@ -9,7 +9,7 @@
 import { normalizeBusinessDateKey } from "../shared/business-date"
 import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
 import { dailyReportSseMessageSchema } from "../shared/sse-schema"
-import type { DailyReportAuthenticate, DailyReportEncodeUserId, DailyReportRedisProvider } from "./ports"
+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 +24,256 @@ const jsonData = (payload: unknown, init?: { status?: number }): Response =>
         headers: { "Content-Type": "application/json" },
     })
 
+// ---------------- 添付配信の定数とヘルパー (純粋・モジュールスコープ) ----------------
+
+/** 添付 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 +281,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 +315,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 (画面ルート) ----------------
 
@@ -540,9 +809,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 },
     }
 }

package/src/server/ports.ts

@@ -66,3 +66,77 @@ export type DailyReportResolveUserId = (externalUserId: string) => Promise<numbe
  * 内部数値ユーザー ID をクライアント公開用に難読化するポート。
  */
 export type DailyReportEncodeUserId = (id: number) => string
+
+/**
+ * Reversible obfuscation codec for an internal numeric id exposed to clients.
+ * クライアントへ公開する内部数値 ID の可逆難読化コーデック。
+ *
+ * これは難読化であって認可ではない。トークンを能力 (capability) として扱ってはならず、
+ * 認可は必ずサーバー側の述語で行うこと。ID 空間を混ぜないため、リソース種別ごとに
+ * 別インスタンス (別 alphabet 等) を注入することを推奨する。
+ */
+export type DailyReportIdCodec = {
+    /** 内部数値 ID をトークンへ変換する。 */
+    encode: (id: number) => string
+    /** トークンを内部数値 ID へ戻す。復号できない場合は null。 */
+    decode: (token: string) => number | null
+}
+
+/**
+ * Failure kinds a caller maps onto HTTP statuses.
+ * 呼び出し側が HTTP ステータスへ写像する失敗種別。
+ *
+ * - `not_found`: 実体が存在しない (消失・未正規化 URI)
+ * - `denied`: ストレージ側で拒否された (サンドボックス外・ACL)
+ * - `too_large`: 上限超過 (事前サイズ判定またはワイヤ上限)
+ * - `invalid_path`: 受け入れないスキーム・不正なパス (データ不備)
+ * - `unavailable`: ストレージサービスへ到達できない・締め切り超過
+ */
+export type DailyReportAttachmentFailure = "not_found" | "denied" | "too_large" | "invalid_path" | "unavailable"
+
+/** 添付ファイル読み取りの成功結果。 */
+export type DailyReportAttachmentBytes = {
+    ok: true
+    /**
+     * Byte view backed by an `ArrayBuffer`.
+     * `ArrayBuffer` を裏に持つバイトビュー。
+     *
+     * 素の `Uint8Array` と書くと `Uint8Array<ArrayBufferLike>` へ広がり `BodyInit` へ代入できない
+     * (TypeScript 5.7 以降の既定型引数)。`Response` のボディへそのまま渡すため narrow 型で受ける。
+     * `head` が true の呼び出しでは長さ 0 のビューを返してよい (実サイズは `size` で申告する)。
+     */
+    bytes: Uint8Array<ArrayBuffer>
+    /** バックエンドが申告した MIME 型。判定できない場合は null。 */
+    contentType?: string | null
+    /**
+     * Entity size in bytes, independent of how many bytes `bytes` actually holds.
+     * 実体のバイト数。`bytes` が実際に保持している長さとは独立に申告する値。
+     *
+     * HEAD 応答の `Content-Length` は同じ URI への GET が返す値と一致しなければならない
+     * (RFC 9110 §9.3.2)。`head` が true の呼び出しは本体を読まないため `bytes` は空になるので、
+     * ここで実サイズを申告しないと HEAD が常に `Content-Length: 0` を返してしまう。
+     * 申告できない場合は省略してよく、そのとき呼び出し側は `bytes.byteLength` を使う。
+     */
+    size?: number
+}
+
+/** 添付ファイル読み取りの失敗結果。 */
+export type DailyReportAttachmentError = {
+    ok: false
+    reason: DailyReportAttachmentFailure
+    /** 診断ログ用の生のストレージエラーコード。HTTP ステータスの決定には使わない。 */
+    code?: string
+}
+
+/**
+ * Reads attachment bytes from the host application's storage backend.
+ * ホストアプリのストレージバックエンドから添付ファイルのバイト列を読み取るポート。
+ *
+ * `filePath` はサーバー内部にとどまり、クライアントへは決して渡らない。
+ * 失敗は種別付きで返すこと (例外を投げない・単一の null へ潰さない)。
+ * 種別を潰すと「実体が消えた」「上限超過」「サービス停止」が運用上区別できなくなる。
+ *
+ * `head` が true のときは実体を読まずメタデータのみ取得する。HEAD 要求で本体を読んで
+ * 捨てると、認証済み呼び出し元が任意に転送量とレイテンシを増幅できる経路になる。
+ */
+export type DailyReportReadAttachment = (filePath: string, options: { maxBytes: number; head: boolean; principal?: string }) => Promise<DailyReportAttachmentBytes | DailyReportAttachmentError>

package/src/server/schema.ts

@@ -6,7 +6,7 @@
  * 新規プロジェクトは `defineDailyReportSchema()` で同一構造のテーブル定義を生成できる。
  */
 import { desc, sql } from "drizzle-orm"
-import { type AnyMsSqlColumn, bigint, bit, date, datetime2, foreignKey, index, int, mssqlSchema, nvarchar, primaryKey } from "drizzle-orm/mssql-core"
+import { type AnyMsSqlColumn, bigint, bit, date, datetime2, foreignKey, index, int, mssqlSchema, nvarchar, primaryKey, uniqueIndex } from "drizzle-orm/mssql-core"
 
 /** 注入する外部ユーザーテーブルの最小形 (id / display_name)。 */
 export type DailyReportUserTable = { id: AnyMsSqlColumn; displayName: AnyMsSqlColumn }
@@ -85,19 +85,50 @@ export type DailyReportUserStatusTable = {
     updatedBy: AnyMsSqlColumn
 }
 
-/** サービスへ注入するテーブル一式 (アプリ既存モデルまたは本ファクトリ生成物)。 */
+/**
+ * DailyReportAttachment テーブルの構造形。
+ *
+ * `uploadedBy` は外部取込ソース由来の行に投稿者が存在しないため NULL 許容。
+ * `sourceKey` は取込の冪等 upsert の自然キー。
+ * `objectCheckedAt` / `objectMissingAt` から実体存在の三値 (unknown / present / absent) を導出する。
+ */
+export type DailyReportAttachmentTable = {
+    id: AnyMsSqlColumn
+    hubId: AnyMsSqlColumn
+    uploadedBy: AnyMsSqlColumn
+    sourceKey: AnyMsSqlColumn
+    fileName: AnyMsSqlColumn
+    filePath: AnyMsSqlColumn
+    fileType: AnyMsSqlColumn
+    fileSize: AnyMsSqlColumn
+    objectCheckedAt: AnyMsSqlColumn
+    objectMissingAt: AnyMsSqlColumn
+    createdAt: AnyMsSqlColumn
+    createdBy: AnyMsSqlColumn
+    updatedAt: AnyMsSqlColumn
+    updatedBy: AnyMsSqlColumn
+}
+
+/**
+ * サービスへ注入するテーブル一式 (アプリ既存モデルまたは本ファクトリ生成物)。
+ *
+ * `attachment` のみ任意。添付テーブルを持たない消費アプリでも本パッケージを使えるようにするため。
+ * 未注入時は詳細の `attachments` が常に空配列になり、添付エンドポイントは全トークンで 404 を返す
+ * (意図した縮退動作)。
+ */
 export type DailyReportTables = {
     hub: DailyReportHubTable
     internal: DailyReportInternalTable
     comment: DailyReportCommentTable
+    attachment?: DailyReportAttachmentTable
     label: DailyReportLabelTable
     hubLabel: DailyReportHubLabelTable
     userStatus: DailyReportUserStatusTable
 }
 
 /**
- * Generic factory: build the six daily-report tables under an arbitrary schema name.
- * 任意のスキーマ名の下に日報 6 テーブルを生成する汎用ファクトリ。
+ * Generic factory: build the seven daily-report tables under an arbitrary schema name.
+ * 任意のスキーマ名の下に日報 7 テーブルを生成する汎用ファクトリ。
  *
  * 制約・索引名は `${schemaName}_<Table>_...` 規約で生成する。
  * ユーザーテーブルへの FK は注入された `userTable` を参照する。
@@ -262,5 +293,49 @@ export function defineDailyReportSchema<S extends string>(schemaName: S, opts: {
         ],
     )
 
-    return { hub, internal, comment, label, hubLabel, userStatus } satisfies DailyReportTables
+    const attachment = s.table(
+        "DailyReportAttachment",
+        {
+            id: bigint("id", { mode: "number" }).identity().notNull(),
+            hubId: bigint("hub_id", { mode: "number" }).notNull(),
+            // 外部取込ソース由来の行には投稿者が存在しないため NULL 許容
+            uploadedBy: bigint("uploaded_by", { mode: "number" }),
+            // 取込の冪等 upsert の自然キー。`<source>:<external-id>` 形式を推奨 (値の規約は消費アプリが決める)
+            sourceKey: nvarchar("source_key", { length: 200 }).notNull(),
+            fileName: nvarchar("file_name", { length: 255 }).notNull(),
+            // ストレージ URI。受け入れるのは `gcs://` のみ (取込側で表明・読み取り側で再検証)
+            filePath: nvarchar("file_path", { length: "max" }).notNull(),
+            fileType: nvarchar("file_type", { length: 100 }),
+            fileSize: bigint("file_size", { mode: "number" }),
+            // 実体存在の三値をこの 2 列から導出する:
+            //   objectCheckedAt が null      -> unknown (未検証)
+            //   objectMissingAt が非 null    -> absent  (消失を確認)
+            //   上記以外                      -> present (実在を確認)
+            objectCheckedAt: datetime2("object_checked_at"),
+            objectMissingAt: datetime2("object_missing_at"),
+            createdAt: datetime2("created_at").notNull(),
+            createdBy: nvarchar("created_by", { length: 50 }).notNull(),
+            updatedAt: datetime2("updated_at").notNull(),
+            updatedBy: nvarchar("updated_by", { length: 50 }).notNull(),
+        },
+        (table) => [
+            primaryKey({ name: `${schemaName}_DailyReportAttachment_pk`, columns: [table.id] }),
+            foreignKey({
+                name: `${schemaName}_DailyReportAttachment_hub_id_fk`,
+                columns: [table.hubId],
+                foreignColumns: [hub.id],
+            }),
+            foreignKey({
+                name: `${schemaName}_DailyReportAttachment_uploaded_by_fk`,
+                columns: [table.uploadedBy],
+                foreignColumns: [users.id],
+            }),
+            // 取込の冪等性を DB 側で担保する
+            uniqueIndex(`${schemaName}_DailyReportAttachment_source_unique`).on(table.hubId, table.sourceKey),
+            // 一括取得 (hub_id IN (...) ORDER BY created_at) を被覆する
+            index(`${schemaName}_DailyReportAttachment_hub_id_index`).on(table.hubId, table.createdAt),
+        ],
+    )
+
+    return { hub, internal, comment, attachment, label, hubLabel, userStatus } satisfies DailyReportTables
 }