まず値を置く場所を決める
検索に使う値が A&B "C" だとします。URL のクエリー値では、アンパサンドは通常パラメーターを区切るため、クエリー文字列を組み立てる前に値の一部として符号化する必要があります。HTML のテキストではアンパサンドが文字参照を始めることがあり、山括弧はマークアップを始める可能性があります。JavaScript の文字列リテラル内では、引用符とバックスラッシュに独自の構文があります。これらは別々の解析文脈です。ある文脈で安全な出力が次の文脈でも安全とは限りません。実際のアプリでは文字列を連結してマークアップを作るより、挿入先を理解するプラットフォームの API やテンプレートを使ってください。
URL のクエリー値を組み立てる
クエリのキーが q なら、値を1つの URL コンポーネントとしてエンコードし、q= の後に置きます。アンパサンドは %26 になり、引用符も URL エンコーダーの規則に従って表されます。完成済み URL 全体を1つの値としてエンコードすると、構造を表す句読記号までエンコードされ、誤ったアドレスになります。得られた URL を HTML ページ内のリンク文字列として表示する場合、そのテキストノードには HTML に安全な表現が必要です。HTML 属性に入れる場合は、独自の引用規則を持つ属性向けの安全なシリアライザーを使ってください。
- 元の値：A&B "C"
- URL の値：クエリーの区切り文字を符号化
- HTML または JavaScript：出力先に合わせてエスケープ
JavaScript と HTML は別の文脈
スクリプトが元の値を引用符付きの文字列リテラルに保存する場合は、JavaScript の文字列用エスケープが必要です。これはソースコード上の文脈に合わせた処理であり、URL コンポーネントの符号化や HTML 出力用のエンコードを代替しません。信頼できない入力をインラインスクリプトのソースへ直接入れないでください。保守されているフレームワークで適切に実装するなら、データ属性や、慎重にシリアライズした JSON を含むスクリプト要素を使う方が安全な場合があります。MultiVerto の JavaScript エスケープツールは文字列リテラル中の文字の扱いを示しますが、アプリ全体がスクリプト挿入に対して安全だと証明するものではありません。安全性は実際のパーサーの文脈と周囲のコードによって決まります。
復号は処理と逆の順序で行う
受け取り側では、URL パーサーがパラメーター q を取り出し、その値のパーセント表記を一度だけ復号します。HTML パーサーは文書を組み立てる際に文字参照を処理しますが、ブラウザーはページに普通のテキストが見えるというだけで、その中のパーセント表記を復号しません。JavaScript はソースコードを解析するときに自身の文字列リテラルのエスケープを解釈します。異なる文脈のデコーダーを使うと、%26 のような表記がそのまま見えたり、次の文脈で構文として解釈されるデータを作ったりします。元の未加工の値は、用途ごとに直列化した表現と分けて保管し、画面表示用の文字列を誤って次の処理の入力にしないでください。
実際のアプリで確かめること
元の値が URL の構成要素、HTML のテキストまたは属性、必要ならスクリプトへと渡る経路を書き出します。各段階で、その出力先に合った API を選び、アンパサンド、引用符、小なり記号、ASCII 以外の文字で試してください。途中のエンコード済み文字列だけで判断せず、最後に表示されたページと、解析後の URL を確かめます。エスケープは値の信頼性を保証したり、リンク先を検証したりしません。別の方針による確認が必要な場合もあります。リンク先の変換器は、フレームワークに実装する前に各段階を小さな例で理解する助けになります。