manage-headers

プラグインの確認：node "${PLUGIN_ROOT}/scripts/check-version.js" を実行します。メッセージが出力された場合は、先にユーザーに表示してから続行してください。

ヘッダーを管理する

Power Pages サイトの HTTP セキュリティヘッダーを確認して設定します。ヘッダーは、.powerpages-site/site-settings/ 内の YAML ファイルに保存される HTTP/* サイト設定として構成されています。

初期リクエスト： $ARGUMENTS

注意事項

• サイト設定は YAML ファイルです。 各ヘッダーは .powerpages-site/site-settings/ 内の個別の .yml ファイルです。ファイル名では / の代わりに - を使用します（例：HTTP/X-Frame-Options → http-x-frame-options.sitesetting.yml）。
• 設定がない場合、ヘッダーもありません。 サイト設定が存在しない場合、実行時にそのヘッダーは完全に省略されます（新しいサイトの CSP を除く。headers-reference.md を参照）。
• HSTS と Cache-Control はプラットフォームによって管理されます。 HTTP/Strict-Transport-Security を設定しようとしないでください。実行時には認識されず、設定しても効果はありません。
• Maker モードではヘッダーが無効になります。 Power Pages Studio からのリクエストでは、すべての HTTP/* ヘッダーの出力がスキップされます。ヘッダーはスタジオのプレビューではなく、シークレットタブで確認してください。
• CSP はそのまま出力されます。 実行時に値がそのまま出力され、ランタイムのソースが自動的に統合されることはありません。サイトが動作しなくなるため、CSP には Power Pages ランタイムのホストを含める必要があります。
• CSP nonce。 script-src に 'nonce' が含まれている場合、実行時にリクエストごとに 'nonce-<random>' に置き換えられ、インラインイベントハンドラーのハッシュが自動生成されます。document.createElement を介して動的に作成されたスクリプトには nonce が付与されません。
• SameSite=None には HTTPS が必要です。 HTTPS では、実行時にすべての Cookie に Secure が自動設定されます。
• CORS の * は自動的に個別化されます。 実行時にリクエストごとに * がリクエスト元の特定の Origin に置き換えられます。ブラウザーにはワイルドカードではなく、単一の Origin を指定するヘッダーが表示されます。

ワークフロー

1. 前提条件 — プロジェクトを特定し、site-settings ディレクトリが存在することを確認します
2. 現在のヘッダーを確認 — サイト設定の YAML ファイルを読み、設定済みのヘッダーと不足しているヘッダーを特定します
3. 評価して計画 — 不足している項目を特定し、推奨事項を提示します
4. 変更を適用 — 既存の設定を編集するか、新しい設定を作成します
5. 要約 — 結果を提示し、使用状況を記録して、追加の対応を提案します

タスクの追跡

4 つのグループに分けてタスクを作成します。各タスクは、開始時に in_progress、完了時に completed に設定します。

グループ	作成するタイミング	タスク
1	開始時	前提条件を確認
2	前提条件の確認後	現在のヘッダーを確認 · 評価して計画（レビュー モードでは「評価して計画」をスキップ）
3	ユーザーが変更を承認した後	変更を適用（レビュー モード、または変更が承認されなかった場合はスキップ）
4	適用または評価の後	要約（常に実行）

---

1. 前提条件

1.1 プロジェクトを特定し、レビュー モードを検出する

Glob を使用して **/powerpages.config.json を検索します。$ARGUMENTS に --review <out-dir> が含まれている場合は、出力ディレクトリを記録します。この場合、ステップ 3～4 はスキップされ、ステップ 5 では JSON のみを書き出します。

1.2 site-settings ディレクトリを確認する

.powerpages-site/site-settings/ が存在することを確認します。存在しない場合、サイトはまだデプロイされていません。ユーザーにその旨を伝え、/deploy-site を推奨して終了します。

---

2. 現在のヘッダーを確認する

Glob を使って、.powerpages-site/site-settings/ 内のすべての *.yml ファイルを検索します。Read を使って各ファイルを読み取り、name フィールドと value フィールドを抽出します。HTTP/ で始まる設定をすべて特定します。これらが設定済みのヘッダーです。

references/headers-reference.md にある認識済みヘッダーの一覧と比較します。一覧にあるヘッダーごとに、次のように記録します。

• 設定済み — 現在の値を記録します。
• 未設定 — 未設定として記録し、headers-reference.md に記載されている推奨値を記録します。

CSP については、HTTP/Content-Security-Policy が設定されている場合、Glob と Read を使ってプロジェクトのソースファイルを検索し、外部 URL がポリシーで許可されているか確認します。pac auth who でサイトのクラウド環境を特定し、正しい Power Pages ランタイムホストを確認します（headers-reference.md の「Power-Pages-runtime sources a CSP must allow」を参照）。

---

3. 評価と計画

レビュー モードではスキップします。

平易な言葉だけを使ってください。CSP、CORS、HSTS、MIME スニッフィングなどの言葉から説明を始めないでください。日常的な言葉で説明します。

ヘッダーの概念	平易な表現
Content-Security-Policy	「ブラウザーが読み込めるスクリプトやリソースを指定するもの」
X-Frame-Options / frame-ancestors	「ほかの Web サイトが自分のサイトをフレーム内に表示できるかどうか」
X-Content-Type-Options	「ブラウザーによるファイル形式の推測を防ぐもの」
CORS headers	「ほかの Web サイトが自分のサイトのデータを呼び出せるかどうか」
SameSite cookies	「ブラウザーがサインイン Cookie を送信するタイミング」

デフォルトの進め方

推奨値とガイダンスについては、references/headers-reference.md を読みます。最も重要な不足項目から提示します。推奨値と比較して、未設定または誤った値に設定されているヘッダーを優先します。

🚦 ゲート（計画 · manage-headers:3.per-finding）： 項目ごとのループ — ヘッダーの不足項目ごとに、承認／カスタマイズ／スキップを確認します。ループ内の項目ごとに実行されます。スキップした項目ではヘッダーは現在の値のままになり、承認またはカスタマイズした項目ではフェーズ 4 で Edit / create-script の呼び出しが行われます。

実行条件： フェーズ 3 の開始時に、references/headers-reference.md に照らしてヘッダーの不足項目が集計されていること。 確認する理由： 自動承認すると、サイトが動作しなくなる CSP/CORS の値が適用される可能性があります（必要なスクリプトがブロックされる、サードパーティーのウィジェットが拒否されるなど）。自動スキップすると、サイトに重要なヘッダーが設定されないままになります。 キャンセル時の影響： ありません — フェーズ 4 の Edit / create-script の呼び出しは、承認した項目に対してのみ実行されます。

各項目について、AskUserQuestion を使って次の内容を提示します。

• 変更が重要である理由を平易な言葉で説明します。
• 推奨値を示します。
• 選択肢として、推奨値を承認する、カスタマイズする、スキップする、を提示します。

すべてのヘッダーを一度に提示しないでください。重要な不足項目から提示します。すでに推奨値に設定されているヘッダーは、対応を求めずに概要で説明します。

CSP の組み立て

ユーザーが CSP を必要としている場合（未設定または不完全な場合）、次の内容を使って組み立てます。

1. headers-reference.md の基本テンプレート
2. クラウド環境に合ったランタイムホスト
3. プロジェクトのソースファイルから見つかった外部 URL — すべてのソースファイル、テンプレート、スクリプトなどを検索します。
4. インラインスクリプト用の 'nonce' キーワード

既存の CSP を確認する場合は、次の点を検証します。

• サイトが実際に読み込むすべての外部 URL がポリシーで許可されていること
• サイトのクラウド環境に対応したランタイムホストが含まれていること

組み立てた CSP または修正した CSP を確認用に提示します。適用を強制する前に、レポート専用モード（HTTP/Content-Security-Policy-Report-Only）で開始することを推奨します。

---

4. 変更を適用する

レビュー モードではスキップします。

既存の設定の場合：YAML ファイルを直接 Edit し、value フィールドを変更します。

新しい設定の場合：共有の作成スクリプトを使います。

node "${PLUGIN_ROOT}/scripts/create-site-setting.js" \
  --projectRoot "<PROJECT_ROOT>" \
  --name "<setting-name>" \
  --value "<value>" \
  --description "<description>"

詳細については、references/commands.md を参照してください。

すべての変更を適用した後、デプロイするかどうかを確認します。「これらの変更をデプロイしますか？変更は次回のデプロイ後に反映されます。」と尋ねます。はいの場合は、/deploy-site を呼び出します。

---

5. 要約する

5.1 レビューモード

まず、設定済みの HTTP/* サイト設定を読み込みます（ステップ 2 で取得済みです）。次に、各ヘッダーの平易な説明と、設定値に実際の問題（重要な指示の不足、値が弱いなど）がある場合は推奨する修正を記載した <REVIEW_DIR>/header-annotations.json を作成します。変換スクリプトでは、ヘッダーの説明をハードコードしなくなりました。説明はあなたが記述します。

{
  "headers": {
    "HTTP/<HeaderName>": { "description": "What this header does, in plain language.", "fix": "Optional fix if the configured value has a genuine issue." }
  }
}

信頼できる説明と検証ルールについては、references/headers-reference.md を使用してください。値に実際の問題がある場合にのみfixを提示してください。すべてのヘッダーに意見を述べる必要はありません。

次に、変換を実行します。

node "${PLUGIN_ROOT}/skills/manage-headers/scripts/transform-headers.js" \
  --projectRoot "<PROJECT_ROOT>" \
  --annotations "<REVIEW_DIR>/header-annotations.json"

標準出力を <REVIEW_DIR>/manage-headers.json に書き込み、そこで終了します。変換によって { status, findings, details } が出力されます。結果の提示は、オーケストレーションを行うスキルが担当します。

5.2 概要の提示

レビューモードでは省略します。

平易な言葉で概要を説明します。変更内容、残っている問題、すでに適切に設定されている点を伝えます。

5.3 スキルの使用状況を記録する

参照：${PLUGIN_ROOT}/references/skill-tracking-reference.md

--skillName "ManageHeaders" を使用してください。

5.4 次の対応を提案する

調査結果を踏まえて自然な次の対応がある場合は、それを提案します。意味のある次の対応がなければ、スキルを終了します。

---

制約

• 平易な言葉を使う — ユーザーに技術用語を使ってはいけません。ヘッダー名は日常的な言葉で説明してください。
• headers-reference.md を信頼できる唯一の情報源とする — 推奨値と認識対象のヘッダーカタログは、ここに記載されています。評価の前に読んでください。
• 状況に応じたやり取りを行う — 推奨内容は必ず、サイトの実際の設定と使用状況を反映させてください。
  • 値を推奨する前に、サイトのソースファイル、連携機能、認証設定を確認してください。
  • サイトの機能を損なわないと確認できていない値は、絶対に推奨しないでください（headers-reference.md の「確認するコンテキスト」列を参照）。
  • 変更を提案する際は、既存の値にも触れてください。意図的に設定されている可能性があります。
  • CSP については、プロジェクトのソースファイルで見つかった実際の外部 URL を参照してください。
  • CORS については、スコープを限定する前に、サイトを実際に利用する異なるオリジンのクライアントを確認してください。
  • Cross-Origin-Opener-Policy については、サイトでポップアップを使った認証を行うか確認してください。
  • Cross-Origin-Resource-Policy については、サイトが Azure AD B2C のカスタムログインページをホストしているか、異なるオリジンから埋め込まれているか、またはサイトのリソースを読み込む連携機能があるか確認してください。不明な場合は設定しないか、cross-origin を使用してください。
• プレビューは変更確認専用 — 設定値を変更するオプションにのみ preview を含めてください。情報提供のみの選択肢には追加しないでください。
• 推奨によってサイトの機能を損なわないこと — 値を推奨する前に、サイトで実際に使用されているリソースがブロックされないか検討してください。CSP については、実行時のソースとプロジェクト内の外部 URL が必ず含まれていることを確認してください。CORS については、サイトで実際に異なるオリジンとの連携が必要か確認してください。不明な場合は、まずレポートのみのモードを推奨してください。
• 既存のポリシーの制限を緩める提案は絶対にしない — ユーザーがすでに制限の厳しい CSP、CORS のスコープ、またはヘッダー値を設定している場合、制限を緩める提案はしないでください。正常に機能している厳格なポリシーは、広範なポリシーより優れています。CSP ディレクティブで https: のワイルドカードを推奨してはいけません。具体的なホストを列挙してください。
• 変更後にデプロイする — ヘッダーの変更はデプロイ後にのみ有効になります。変更を適用した後は、必ず /deploy-site を提案してください。

参照資料

• references/headers-reference.md — 認識対象のヘッダーカタログ、推奨値、CSP の構成ルール、実行時のソース。対話モードでステップ 2（調査）とステップ 3（評価）を行う前に読んでください。
• references/commands.md — 共通の create-site-setting.js の使用方法。新しい設定を作成するステップ 4（適用）で読んでください。