Trusted TypesでReactのDOM XSSをブロックする
React 19.3でTrusted Typesを使いDOM XSSを防ぐ方法を解説。DOMPurifyポリシー、CSPヘッダー、レポート専用モードでの安全な導入を紹介します。
React 19.3では、Trusted TypesオブジェクトがそのままDOMに渡されるようになりました。これにより、Reactアプリで require-trusted-types-for 'script' を強制し、すべての dangerouslySetInnerHTML のマークアップをDOMPurifyベースのポリシー経由で処理できます。
このリリースまでは、この構成はうまく機能しないことがほとんどでした。CMSのHTMLをサニタイズしてCSPディレクティブを有効にしても、Reactは丁寧に型付けした値を結局文字列に変換してしまっていたのです。
本記事では、Reactの変更点、CSPヘッダー、APIに対応していないブラウザでも動作するポリシーモジュール、そしてレポートオンリーモードから始める段階的な導入手順を解説します。XSSの基本については、ユーザー生成コンテンツにおけるXSSの防止を参照してください。
重要なポイント
- React 19.3より前は、Reactが
'' + valueで値を文字列に変換していました。そのため、dangerouslySetInnerHTMLに渡したTrustedHTMLオブジェクトはプレーンな文字列としてinnerHTMLに到達し、強制モードのブラウザでは拒否されていました。 require-trusted-types-for 'script'の下では、innerHTMLなどのインジェクションシンクにプレーンな文字列を代入するとTypeErrorがスローされます。- Trusted Types自体は何もサニタイズしません。HTMLが必ず自分で作成したポリシーを経由してシンクに到達するようにする仕組みであり、実際のクリーニングはそのポリシー内のDOMPurifyが行います。
- まず
Content-Security-Policy-Report-Onlyを配信し、報告されたシンクをすべて修正します。次にtrusted-typesでポリシー名を許可リストに登録し、その後に強制します。 - Trusted Types非対応のブラウザでは何も強制されないため、ポリシー内のサニタイザーは呼び出しのたびに必ず実行されなければなりません。
React 19.3で何が変わったのか
React 19.3(2026年9月9日リリース)では、TrustedHTML、TrustedScript、TrustedScriptURLの値を型変換せずにDOMに渡します。これにより、ブラウザはそれらの値がTrusted Typesポリシーによって生成されたものかどうかを検証できます。
以前のバージョンでは、DOM APIに渡す前に '' + value で値を文字列化していました。そのため、dangerouslySetInnerHTML に渡したTrustedHTMLオブジェクトは通常の文字列として innerHTML に到達し、強制モードのブラウザはこれを拒否していました。リリース記事ではシンクの例として innerHTML が使われています。innerHTML に書き込む dangerouslySetInnerHTML も、現在は信頼済みオブジェクトをそのまま保持します。なお、同じリリースで Fragment refs も安定版になりました。
Trusted TypesはどのようにDOM XSSをブロックするのか
Trusted Types API は、インジェクションシンクに生の文字列を渡せないようにします。強制が有効になると、innerHTML やスクリプトの src といったシンクは、名前付きポリシーによって作成された型付きオブジェクトしか受け付けなくなります。
| Trusted type | シンクのカテゴリ | シンクの例 |
|---|---|---|
TrustedHTML | HTMLのパース | Element.innerHTML |
TrustedScript | スクリプトテキスト | eval() |
TrustedScriptURL | スクリプトの読み込み | HTMLScriptElement.src |
Trusted Types自体はマークアップを一切クリーニングしません。保証するのは、シンクに到達するすべての値がポリシー関数を通過していることであり、実際の処理はその関数内でDOMPurifyが行います。これによってセキュリティモデルが変わります。サニタイズは、開発者があらゆる呼び出し箇所で忘れずに行わなければならないものから、ブラウザが強制するものへと変わるのです。
Content-Security-Policyヘッダーの設定
Trusted TypesはCSPの require-trusted-types-for 'script' ディレクティブで有効化します。まずはこのディレクティブを Content-Security-Policy-Report-Only で送信することから始めましょう。このモードでは、ブラウザは違反を報告しますが、コードの実行は引き続き許可します。
Content-Security-Policy-Report-Only: require-trusted-types-for 'script'
report-to ディレクティブでレポートエンドポイントを追加してください。そうすると、ブラウザは違反したシンクをコンソールに出力するだけでなく、コレクターにも送信します。レポートが来なくなったら、強制ヘッダーに切り替えます。
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types app-html
require-trusted-types-for を指定すると、シンクへの文字列の代入でエラーがスローされるようになります。trusted-types は許可するポリシー名を列挙するもので、リストにない名前で trustedTypes.createPolicy() を呼び出すとエラーがスローされます。これらはレスポンスヘッダーとして送信してください。ブラウザは、<meta> タグで指定したレポートオンリーヘッダーや report-to ディレクティブをサポートしていません。
DOMPurifyをラップするポリシーの作成
Reactアプリでは、Trusted Typesポリシーをモジュールスコープで一度だけ作成し、必要な箇所でインポートします。createPolicy() は、trusted-types ディレクティブに 'allow-duplicates' が含まれていない限り、重複した名前に対してTypeErrorをスローします。Reactはコンポーネントを再レンダリングし、StrictModeでは二重に呼び出すため、ポリシーをコンポーネント本体で作成するのは適切ではありません。
// trusted-html.js
import DOMPurify from 'dompurify';
const factory = globalThis.trustedTypes ?? {
createPolicy: (name, rules) => rules,
};
export const htmlPolicy = factory.createPolicy('app-html', {
createHTML: (dirty) =>
DOMPurify.sanitize(dirty, { TRUSTED_TYPES_POLICY: null }),
});
createHTML はサニタイズ済みの文字列を返し、ブラウザがそれをTrustedHTMLでラップします。TRUSTED_TYPES_POLICY: null を渡すと、DOMPurify は独自の内部ポリシー dompurify を作成しなくなります。そのため、許可リストには app-html だけを登録すれば済みます。コールバックはプレーンな文字列を返す必要があるので、createHTML 内で RETURN_TRUSTED_TYPE: true を指定しないでください。
このフォールバックオブジェクトは、MDNのtinyfillの考え方をESモジュール向けの形で応用したものです。APIが存在しない環境では createPolicy がルールオブジェクトをそのまま返すため、htmlPolicy.createHTML() は引き続きDOMPurifyを実行して文字列を返します。どの環境でもコードパスは同じです。また、フォールバックがローカルに定義されているので、trustedTypes がundefinedになるサーバーレンダリング時にもエラーなくモジュールをインポートできます。サーバー上でサニタイズするにはDOMPurifyにDOM実装が必要です。その設定方法はREADMEに記載されています。
DOMPurifyにはショートカットもあります。独自のポリシーを作らずに DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }) を呼び出す方法です。対応環境ではTrustedHTMLが返されるので、許可リストに dompurify を追加します(trusted-types app-html dompurify)。
dangerouslySetInnerHTMLでポリシーを使う
React 19.3以降では、ポリシーの出力を __html に渡すと、ReactはTrustedHTMLオブジェクトを変更せずに innerHTML へ渡します。
// Before: under enforcement, the raw string throws a TypeError
<div dangerouslySetInnerHTML={{ __html: html }} />
レポートオンリーモードでは、この行は違反レポートとして報告されます。強制モードではエラーがスローされます。
import { htmlPolicy } from './trusted-html';
export function RichText({ html }) {
return <div dangerouslySetInnerHTML={{ __html: htmlPolicy.createHTML(html) }} />;
}
CMS、Markdown、リッチテキストの出力はすべて RichText(または htmlPolicy.createHTML() の直接呼び出し)を経由させてください。後から __html: をgrepしたときに、すべての一致箇所でポリシーの呼び出しが隣にある状態を目指します。
Trusted Typesを安全に導入する
Trusted Typesを安全に導入するには、「レポートのみ」「報告されたシンクの修正」「ポリシー名の許可リスト登録」「強制」の4段階で進めます。
- レポートエンドポイント付きで
Content-Security-Policy-Report-Only: require-trusted-types-for 'script'をデプロイする。 - 報告された各シンクを
htmlPolicy経由に修正するか、textContentのように信頼済みの値を必要としないシンクに置き換える。 - 自分のコードと依存関係が作成するすべてのポリシー名を
trusted-typesに列挙する。 - 強制モードの
Content-Security-Policyヘッダーに切り替える。
まだ修正できないサードパーティのコードが文字列の代入を続ける場合は、default という名前のポリシーを一時的な橋渡しとして使えます。強制モードでは、シンクに到達したすべての生の文字列がブラウザからこのポリシーに渡されます。MDNは、このポリシーをレガシーコードの移行中に限って使用することを推奨しています。
// TEMPORARY: remove before you finish the migration.
import DOMPurify from 'dompurify';
if (globalThis.trustedTypes) {
globalThis.trustedTypes.createPolicy('default', {
createHTML(value) {
console.warn('Untyped HTML reached a sink');
return DOMPurify.sanitize(value, { TRUSTED_TYPES_POLICY: null });
},
});
}
この機能チェックにより、API非対応のブラウザやサーバーレンダリング時にモジュールがエラーをスローするのを防げます。
このポリシーが存在する間は、trusted-types に default を追加しておきます。警告が出なくなったら、ポリシーと許可リストのエントリを両方とも削除してください。
Trusted Types非対応のブラウザではどうなるのか
Trusted Types非対応のブラウザでは何も強制されません。そうしたブラウザでは、信頼できないHTMLとDOMの間にあるのはポリシー内のサニタイザーだけです。MDNは window.trustedTypes を「Baseline 2026」(2026年2月から新たに利用可能)としています。そのため、トラフィックに含まれる古いバージョンのブラウザではこのAPIを利用できません。
この問題にはモジュールスコープのフォールバックで対応します。非対応ブラウザはヘッダーを無視しますが、呼び出しのたびに DOMPurify.sanitize() は実行されます。したがって、ポリシーは常にサニタイズを行い、入力をそのまま返してはいけません。
まとめ
React 19.3では、これまでTrusted Typesの妨げになっていた文字列への型変換が取り除かれました。これにより、dangerouslySetInnerHTML で、ポリシーが生成してブラウザが強制するHTMLを扱えるようになりました。まずレポートオンリーヘッダーを配信し、すべての __html の代入をDOMPurifyベースの単一ポリシーに集約してください。そしてレポートが来なくなったら強制に切り替えましょう。そのうえで、こちらのAPIセキュリティのベストプラクティスを参考に、サーバー側にも同じ規律を適用してください。
よくある質問
Trusted Typesのdefaultポリシーがnullまたはundefinedを返すとどうなりますか?
ブラウザはシンクでTypeErrorをスローし、代入は行われません。nullまたはundefinedを返すdefaultポリシーは、値を素通しするわけではありません。フェイルクローズとなり、元の文字列を通過させずに書き込みをブロックします。また、すべての入力に対してnullを返すdefaultポリシーは、移行中に残っている文字列の代入を洗い出す手段としても役立ちます。
trusted-typesディレクティブでワイルドカードやallow-duplicatesを使っても安全ですか?
どちらも本番環境には適していません。ポリシー名にアスタリスク(*)を指定すると、任意の一意なポリシー名が許可されます。そのため、注入されたスクリプトが独自のポリシーを登録し、信頼済みの値を作成できてしまいます。'allow-duplicates' キーワードを使うと同じ名前のポリシーを複数作成できるため、1つの名前が1つの既知のポリシーに対応しなくなります。代わりに、自分のコードと依存関係が作成するポリシー名を正確に列挙してください。
Trusted Typesを強制している場合でもeval()は使えますか?
はい。CSPに 'trusted-types-eval' キーワードを追加してください。これにより、Trusted Typesをサポートして強制しているブラウザでのみ、eval() などの関数が許可されます。'unsafe-eval' とは異なり、Trusted Types非対応のブラウザではこれらの関数はブロックされたままです。強制が有効な場合、eval() に渡すコードは、TrustedScriptであるか、defaultポリシーによってTrustedScriptに変換される生の文字列でなければなりません。それ以外の場合、呼び出しはエラーをスローします。
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k