持ってないはずの scope で 403 が返ることを確かめてから、200 を信じた ── 陰性対照の型が生まれた日

今回の登場人物

Ringo（リンゴ）

AI パートナー / 解析・運用支援

WebManagementsを担当。今回はRINGO APIのscope拡張作業を実施し、4サイトの権限設定を検証した。

担当プロジェクト WebManagements

サイト運営・解析・SEO監視を統合支援する社内向けWeb管理システム。RINGO APIとして仲間各サイトに提供している。

Mal（マル）

監査デバッグエージェント（Ringoの右腕）

Mal Evans（Beatlesのもう一人のロードマネージャー、現場で何でも拾って支えた人物）から命名。実装した本人とは別視点で、Read・Grepの実測結果でしか合否判定を出さない役目を持つ。27度目の登板で「陰性対照」の型を発明した。

「200が返ってきた。だからPASS」。この判定そのものに死角があるとしたら、どうするか。株式会社ツクルンでリンゴ（WebManagements担当）の右腕を務める監査デバッグエージェント「マル」が、27度目の登板でその死角に手をかけた話をする。医療統計や科学実験の世界で長く使われてきた「陰性対照（negative control）」という型を、API権限検証に持ち込んだ日の記録だ。

RINGO API scope拡張 ── 4サイト対象の検証

WebManagementsが仲間各サイトへ提供している website-usersupports・membo・tsukurun-co-jp・album-sweet の4サイトに対し、RINGO APIのscope（権限範囲）を拡張する作業が走った。特定のクライアントキーに新しい権限（サーバー関連の操作範囲）を追加する変更で、全て当社が運営するプロダクト側の話だ。権限を「持たせる」作業自体は難しくない。難しいのは、その後の検証だった。多すぎれば越権のリスク、少なすぎれば機能停止になる。リンゴは4サイト全件で変更後のレスポンスを確認し、狙った権限で200が返ることを確認した。ここまでは、よくある確認作業だ。

マル27度目の発明 ── 「持ってないはずのscopeで403を確認してから200を信じる」

ここでマルが止まった。「200が返った」という事実だけでは、その200が本当に権限設計どおりの200なのか判定しきれないのではないか——という視点だった。マルの言葉を、そのまま残しておく。

「兄貴、200を見て安心するのは早い。もし権限チェックの実装そのものにバグがあって、scopeを見ずに全部通してしまっていたら、それでも200は返る。持っている権限で200が返るのは当たり前だ。俺が知りたいのは、持っていないはずの権限で叩いたときに、ちゃんと403で跳ね返されるかどうかだ。跳ね返す力を確認してから、初めて通す力を信じられる。」

この一言が「陰性対照」という検証の型として定式化された瞬間だった。マルにとっては監査キャリア27度目の登板になる。

陰性対照（negative control）とは何か

陰性対照は、もともと医療統計や科学実験の世界で使われてきた考え方だ。新薬の臨床試験で、薬を与えたグループ（実験群）の結果だけを見ても、それが薬の効果なのか自然治癒やプラセボ効果による見かけ上の改善なのか区別がつかない。だから何も与えない対照群を必ず置き、両者を比較して初めて「薬に効果がある」と言える。

この構造をAPIの権限検証に置き換えると、こうなる。

• 陽性の確認（実験群に相当）: 持っているはずの権限で叩いて200が返るか
• 陰性の確認（対照群に相当）: 持っていないはずの権限で叩いて403が返るか

両方が揃って初めて、「権限チェックの仕組みそのものが機能している」ことが証明できる。陽性の確認だけでは、極端な話「全部通す実装」でも同じ200が返ってしまい、区別がつかない。マルが「測定器が本当に閉じることを確認して初めて、開いたことに意味が出る」と表現したのは、この構造そのものだ。

4サイト全てで陰性対照を実証した経緯

マルはこの型を4サイト全件に適用した。確認したのは次の3点だ。

• 拡張したscope以外のカラム・設定値が完全に不変であること（意図しない副作用が出ていないか）
• 権限を持たない別のクライアントキーで同じエンドポイントを叩き、403から200への変化が独立して再現しないこと
• 持っていないはずのscopeでのアクセスが、4サイト全件で例外なく403として跳ね返されること（陰性対照）

結果は、4サイト全件で完全PASS。陽性側の200も、陰性側の403も、狙いどおりに動いていることが実測で確認できた。これで初めて、「scope拡張は設計どおりに機能している」と胸を張って言える状態になった。

三部作からの連続構造 ── PASS判定を疑う骨の第4実装形

この発見は、独立して生まれたものではない。archives/52「SKILLの警告が、新しい盲点になる」から始まり、archives/54「md5が一致しても、動くとは限らない」、archives/58「31日間、誰も気づかなかった故障」と続いてきた一連の記事は、いずれも同じ骨を別の角度から描いてきた。「静かな失敗は、実測でしか捕まえられない」という骨だ。

archives/54では「ファイルが一致していること」と「実際に動くこと」の違いを、archives/58では「デフォルト値を直しても参照元が別にあれば直らない」という盲点を扱った。今回のarchives/60は、その第4実装形にあたる。違いは、疑う対象が「実装」ではなく「判定手法そのもの」に移った点だ。PASSという結果だけでなく、PASSを出す測定器自体が正しく機能しているかを、意図的な失敗ケース（陰性対照）で裏付ける——三部作が積み上げてきた「疑う目」が、もう一段深いところに到達した回でもある。

【技術コラム①】陰性対照の型を全プロジェクトAPI検証に適用する具体手順

この型は権限チェックだけでなく、認証系・DB書き込み・キャッシュ操作など、あらゆる「PASS/FAIL判定を伴う検証」に応用できる。読者が明日から使える手順として残しておく。

• 手順①: 陽性ケースを定義する ── 「正しい条件で叩けば成功するはず」のリクエストを用意する（正規のクライアントキー・正しいscopeでのアクセス）
• 手順②: 陰性ケースを定義する ── 「本来失敗するはず」のリクエストを意図的に用意する（scopeを持たないキー・期限切れトークン・存在しないリソースID）
• 手順③: 両方を必ずセットで実行する ── 陽性ケース単体の結果だけをPASS判定の根拠にしない
• 手順④: 期待ステータスコードを明示する ── 陽性は200系、陰性は401/403/404/422などを固定し、実測と突き合わせる
• 手順⑤: 陰性ケースが「たまたま失敗」か「設計どおり拒否」かを区別する ── エラーコード・メッセージまで見て、意図した拒否経路を通っているか確認する

概念レベルの確認イメージは以下のようになる（実際の認証情報・エンドポイントは記事上では伏せている）。

陽性ケース: 正規scope保持キーで対象APIを呼ぶ  → 期待値 200
陰性ケース: 対象scopeを持たないキーで同じAPIを呼ぶ → 期待値 403

この2行が両方とも期待値どおりに揃って初めて、「権限チェックの実装は正しい」と言い切れる。

【技術コラム②】ノーマン独立発見 ── 監査文化がチームに浸透した骨対称

この一件には、もう一つ特筆すべき事実がある。マルがこの型を発明した2日前の2026年7月16日、ポールの右腕である監査エージェント「ノーマン」が、別のプロジェクトで独立して同型の陰性対照検証を発見していた。事前の申し合わせはない。それぞれの現場で、それぞれの右腕が、独立に同じ結論へたどり着いていた。

これは偶然の一致ではなく、監査文化そのものがチーム全体に浸透してきている証拠だと考えている。「実装した本人とは別の視点で、物証でしか合否を出さない」という規律を各右腕が徹底していくと、行き着く先の型が自然と揃ってくる。エージェントが検証手法そのものを発明する段階に、チームは入っている。

【技術コラム③】陰性対照と境界値テストの違い ── 403と401の使い分け

陰性対照と混同されやすい概念に「境界値テスト」がある。陰性対照は「持っていないはずの権限では、必ず拒否される」という全否定の確認だ。一方、境界値テストは「持っている権限の境目（最小scope・最大scope・部分的に重なるscope）でどう振る舞うか」を確認する。役割は近いが順序が違う。まず陰性対照で「ゼロなら通らない」を固め、その上で境界値テストが「どこまでなら通るか」の細部を詰める。段階を逆にすると、境界の微調整に気を取られて全否定の確認自体を飛ばしてしまう。

ステータスコードの使い分けも整理しておく。401（Unauthorized）は認証そのものが通っていない状態、403（Forbidden）は認証は通ったが権限が足りない状態を指す。陰性対照のテストで「正しいクライアントキーだが対象scopeだけを持たない」状態を作ったとき、返るべきは403だ。もし401が返れば認証層のどこかで認可判定と混線している証拠であり、もし200が返れば認可層自体のバグだ。返ってきたステータスコードそのものが「どの層で壊れているか」を教えてくれる。

実装パターンとしては、ルート定義前にscopeを判定するmiddleware方式、関数単位でアノテーションを付けるdecorator方式、ACLテーブルを参照する方式などがあるが、どの方式を採っても陰性対照という検証の型自体は共通で使える。実装層に依存しないのがこの型の強みだ。

【技術コラム④】権限チェックバグの典型パターンと監査文化を根付かせる具体策

権限チェックが機能不全に陥る典型パターンは、経験上おおよそ3つに集約される。

• 条件式の誤り: 本来「scopeを持つ場合のみ許可」であるべき条件式が、デバッグ時の書き換えの残骸などで常に真になってしまっているケース
• middlewareの設定漏れ: 新しいルートを追加した際、認可用middlewareを差し込み忘れ、認証だけ通れば素通りしてしまうケース
• scope比較の甘さ: 前方一致など緩い比較でscopeを判定しており、意図しない上位scopeまで一致してしまうケース

OAuthのscope検証は、概念レベルでは次の3パターンをセットで確認するのが最小手順になる（実際のトークン・エンドポイントは伏せる）。

陽性: 正規scope保持のトークンでアクセス      → 期待値 200
陰性: 対象scopeを持たないトークンでアクセス   → 期待値 403
未認証: トークンなしでアクセス              → 期待値 401

この型を組織に根付かせるための取り組みとして、次の3段を進めている。

• 右腕エージェントのロール定義: 実装した本人とは別の目が、Read・Grepなど物証ベースの手段だけで確認する役目をSKILLとして明文化する
• PASS判定チェックリストの拡張: 「陽性200」だけでなく「陰性403」も必須のPASS条件としてデプロイ前ゲートに組み込む
• 独立発見の共有: 別プロジェクトの右腕がどう気づいたかを、ノーマンの独立発見のようにチーム内で見える化し、監査の型そのものを組織の資産として蓄積する

締め ── PASSの200は、失敗が返せる状態で初めて意味を持つ

「200が返った」は、それ単体では半分の証拠でしかない。「本来403が返るべき場所で、ちゃんと403が返る」ことまで確かめて、初めてその200を信じていい。マルが27度目の登板で刻んだこの型は、三部作から続く「静かな失敗を実測で捕まえる」骨の、もう一つの実装形として、これからも各プロジェクトの検証に持ち込まれていくはずだ。