[fix] 本番リリースに向けてAPIのホットパス・エラー表現・権限・CSV出力を修正

[haruto-kamijo]

What & why

本番リリース前に、スキャンのホットパスと管理APIの問題を潰しました。計画と根拠は docs/load-testing.md に残しています。

リリースブロッカー

• 301 → 302 + Cache-Control: no-store。301は無期限キャッシュされるため、(1) 同一端末の再スキャンがAPIに届かず計測が過少になり、(2) 遷移先を変更しても既にスキャンした人には永久に届かない状態でした。既に301を受け取った端末は救済できない(QR再発行=再印刷しかない)ため、ポスター印刷前に入れる必要があります。
• 遷移先URLのプロトコル制限。zod の .string().url() が javascript: / data: / vbscript: / file: を全部通すことを実測で確認しました(zod 3.25.76)。その値をWorkerが302でリダイレクトし、管理UIが として描画するため、プロジェクトを作成・編集できる人による保存型XSS/オープンリダイレクトになっていました(管理画面のオリジンにはAPIトークンがあります)。
• ログインのレート制限。共有パスワード1つに対して制限がなく、自由に総当たりできる状態でした。*.workers.dev にはWAFのレート制限ルールが適用されないため、Workersのレート制限バインディングを使っています。キーは CF-Connecting-IP なので、攻撃者のIPが制限されるだけで正規の管理者は影響を受けません。
• CORSをfail-closedに。ALLOWED_ORIGINS が空のとき '*' にフォールバックしていました。つまり設定漏れやタイポが、Authorization を許可したワイルドカードCORS——最も許容的な設定——に静かに変わる。最もありがちなミスで最悪の設定になるので直しました。
• CSV出力のストリーミング化。従来は全件を .all() してメモリ上で1本の巨大文字列を組み立てており、10万行だとWorkers FreeのCPU 10ms上限を確実に超え(エラー1102)、128MBのisolate上限にも近づきます。混雑したプロジェクトで1回クリックするだけでWorkerが落ちうる状態でした。加えてANALYTICS権限チェックが実装されていなかった(READMEは必須と書いていた)ので追加しました。
• ヘルスチェックと構造化ログ。/healthz と /readyz。GET / はQRリダイレクトのもので ?id= がないと404を返すため、監視先に使うと永遠にアラートが鳴ります。
• セッションTTLを24時間 → 8時間(1イベント日)。全権限のBearerトークンが localStorage にあるため、寿命を縮めるのが最も安価な影響範囲の縮小です。

スキーマ変更(ユニーク制約の張り替え)

想定運用は「ポスターなどの物ごとにQRを1つ生成し、必要であれば場所を記載する」ですが、ユニーク制約が (project_id, medium, location) だったため、場所を空にした2枚目のポスターが409で作成できませんでした。制約が「媒体×場所ごとに1つ」をモデル化していて運用と矛盾していたので、(project_id, name) に張り替え location を任意化しました。副次効果として、名前ベースのダウンロードファイル名がプロジェクト内で一意になります。

あわせて AccessLogs に外部キー(ON DELETE CASCADE)を追加しました。従来は外部キーがなく、プロジェクト削除でスキャン履歴が孤児化してUIから到達できない行が残っていました。行数が少ない今のうちにテーブル再作成をしています。

エラー表現

文言をサーバーが決めていたことが翻訳を不可能にしていました——英語の開発者向け文字列(Invalid request body)が日本語利用者に、ハードコードされた日本語の409が英語利用者に出ていました。src/errors.ts に安定した機械可読コードを定義し、文言はクライアントが持つ形にしました。

性能

• QR参照とプロジェクト参照を1本の leftJoin に統合(逐次往復を1回削減)。
• ログのINSERTを executionCtx.waitUntil へ。D1の書き込みはプライマリ宛で最も遅いのに、来場者には不要な待ち時間でした。LOG_WRITE_MODE=sync でデプロイなしに同期へ戻せます。
• GET /projects は10行を描画するためにページに関係なくAccessLogsとQRCodesの全件をGROUP BYしていました。現ページのIDに絞る形に変更。
• 全一覧エンドポイントに ORDER BY 追加。従来は順序が不定で、作成直後の項目が1ページ目に現れる保証がなく(利用者は作成失敗と考えて作り直す)、ページ間で行が重複・欠落しえました。
• (project_id, accessed_at DESC) の複合インデックスを追加し、冗長になった単一列インデックスを削除(スキャン1件あたりのインデックス書き込みが1つ減ります)。

権限チェック

GET /projects / GET /:id / POST / / PUT /:id / GET /:id/access-logs / CSV が認証のみで認可がなく、READMEの表と食い違っていました。単一管理者に ALL_PERMISSIONS が付く現状では露出しませんが、Verifier の差し替え口を用意した意味が消えるので VIEW / EDIT / ANALYTICS を付けました。

ボット判定

facebook / Discordbot の部分一致だけで、Twitterbot や Slackbot が実スキャンとして黙って計上されていました。判定を src/user-agent.ts に切り出し、除外せず is_bot=1 で記録するようにしました(捨てないので判定を後から改良して過去分を再集計できます)。逆に LINEのアプリ内ブラウザ(Line/13.x)は実ユーザーなので明示的に除外しています——ここを逆にすると最大の実トラフィックが消えます。

How this was tested

• pnpm lint
• pnpm typecheck
• pnpm build
• wrangler dev --local で手動検証

ローカルD1での実測:

• 人間UA / LINEアプリ内ブラウザ → 302 + no-store、line-poker / Twitterbot → 200のOGメタHTML、不明IDは404で書き込みゼロ
• waitUntil の書き込みがリクエスト数と1:1で着地(1,717リクエスト → 20,006 → 21,723)
• is_bot: Line/13.15.0 は 0(3,117行すべて)、line-poker と Twitterbot は 1
• FKカスケードが実D1バインディング経由で動作(アクセスログ2件 → QR削除 → 0件)
• 移行で孤児化ログが除去され、schema.sql の再実行が冪等
• ユニーク制約: 別プロジェクトの同名はOK、同一プロジェクトの同名は UNIQUE constraint failed、場所が空のQRを複数作成できる(旧制約では409)
• javascript: / data: / file: の遷移先URLが400で拒否、https: は201
• 誤パスワード14回で 401×10 → 429×4(正確に10回で切り替わり)、JWTの iat→exp が8時間
• CSV: 5,000行を「5種類の日時だけ」でシードし、2,000行のページ境界が同一日時グループ内に落ちる条件(idのタイブレーカがないと壊れるケース)で重複0・欠落0。 期間指定は 1日=1000行 / 2日=2000行 と一致。上限超過は 413 + {total, max}
• /healthz と /readyz が200、GET / は404、許可オリジンにACAOが付き未許可オリジンには付かない

注意

• CSV_EXPORT_ENABLED は "false" のままです。 上記が全部入ったので有効化は可能ですが、負荷テストのS4を通してから判断するのが安全です。
• Web側がエラーコードを見るのは後続PR(release/web-ux)なので、APIだけ先にデプロイすると、その間は日本語UIでも英語のフォールバック文言が出ます。
• 移行 0002 はテーブル再作成を含む唯一戻しにくい手順です。適用前に wrangler d1 export を取ってください(手順は移行ファイルの冒頭コメントに記載)。