【ITニュース解説】Map Telegram Deep-Link Payloads to MySQL Entities Safely in PHP

ディープリンクは、ユーザーを特定のウェブサイトやアプリケーション内の特定のコンテンツ、または特定の操作フローに直接誘導するための特別なURLだ。Telegramボットの場合、t.me/あなたのボット名?start=PAYLOADのような形式で利用され、ユーザーがこのリンクをクリックすると、Telegramアプリが開き、自動的にボットに/start PAYLOADというメッセージを送信する仕組みになっている。これにより、ユーザーは目的の作業をスムーズに開始できる。

このディープリンクは、外部のマーケティングキャンペーン、提携しているウェブアプリケーション、あるいはメールテンプレートなどからユーザーを特定のボットの機能へ誘導する際に非常に便利だ。例えば、リード顧客の獲得ボットや、カスタムされたECサイトのチェックアウトフローなどに応用できる。

しかし、もしペイロードとしてデータベースの内部的なID、例えば注文番号の7821を直接使用し、t.me/YourBot?start=order_7821のようなリンクを作成してしまうと、大きなセキュリティ上の問題が生じる。ユーザーはブラウザやTelegramの検索バーでこのペイロードを簡単に7822や7823と変更できてしまう。これにより、他のユーザーの事前に割り当てられた注文情報を勝手に閲覧したり、競合他社のリード数を推測したり、データベースの一部だけが更新されるような不正な操作を引き起こしたりする可能性がある。このような脆弱性は「安全でない直接オブジェクト参照（IDOR）」と呼ばれ、重大なリスクとなる。

さらに、Telegramがディープリンクのペイロードに設けている技術的な制約も理解しておく必要がある。ペイロードは最大で64文字までという厳格な文字数制限があり、使用できる文字種も英数字、アンダースコア、ハイフンに厳しく制限されている。一般的なBase64エンコードされた文字列やハイフンを含むUUID（Universally Unique Identifier）のような長い文字列をそのまま使うと、Telegram側で勝手に途中で切り捨てられたり、正しく認識されずにリンクが機能しなくなったりする可能性がある。モバイルクライアントではリンクが壊れてしまうこともあり得る。

そのため、ボットのPHPバックエンドがTelegramからのメッセージを受け取った際には、まずこのペイロードを安全かつ正確に抽出する必要がある。単にスペースで区切って文字列を取り出すような方法では、ユーザーが意図的に複数のスペースを入れたり、許可されていない文字を入れたりした場合に、プログラムがエラーを起こしたり、不正なデータを受け取ってしまったりする危険性がある。これを防ぐためには、正規表現を用いて、Telegramが定める文字数と文字種に厳密に合致するペイロードだけを抽出する仕組みが不可欠だ。不正な形式のペイロードはログに記録し、適切なエラー処理を行うべきだ。

この問題を解決するために、データベースの内部IDを直接使うのではなく、予測不可能な「不透明な暗号化トークン」を生成し、それをペイロードとして利用する方法が推奨される。例えば、PHPのbin2hex(random_bytes(7))という関数を使って、7バイトのランダムなバイナリデータを16進数文字列に変換すると、14文字のランダムな英数字列が生成される。これはTelegramの64文字というペイロード制限に余裕で収まり、0-9a-fのみで構成されるため文字種制限もクリアする。さらに、56ビットものエントロピー（予測不可能性）を持つため、総当たり攻撃で推測することは事実上不可能だ。

このトークンは、実際の操作内容や対象となるデータベースのエンティティ（例えば、特定のリードや注文）と紐付けて、専用のデータベーステーブル（bot_deep_linksのようなテーブル）に保存する。このテーブルには、トークン自体、実行するアクションの種類、対象エンティティのID、生成者、使用されたユーザー、最大使用回数、現在の使用回数、有効期限などの情報を記録する。ディープリンクが発行される前に、PHPバックエンドでこのテーブルに新しいレコードを作成し、そのレコードのトークンを使ってディープリンクURLを生成する。

ユーザーがディープリンクをクリックした際には、ボットは/startコマンドと共にペイロードとして渡されたトークンを受け取る。このトークンを使ってbot_deep_linksテーブルから対応するレコードを検索し、そのレコードに紐付けられた実際のアクションと対象IDを取得する。このとき、単にトークンを検索するだけでなく、トークンが有効期限内であるか、または最大使用回数を超えていないかなども厳密に検証する必要がある。

さらに重要な点として、ユーザーがボットと既に会話中の状態であっても、ディープリンクをクリックする可能性がある。例えば、ユーザーが複数ステップのフォーム入力中にディープリンクをクリックした場合、ボットは/start PAYLOADというメッセージを受け取る。もしボットが単純な会話状態管理に依存していると、このメッセージをフォーム入力の続きと誤解して処理してしまう可能性がある。これを避けるためには、ディープリンクが実行された際には、現在のユーザーの会話状態を明示的にリセットまたは上書きする仕組みが必要だ。

また、ディープリンクの処理は「冪等性」を持つように設計すべきだ。これは、同じディープリンクが複数回クリックされたり、あるいは他のユーザーに転送されてクリックされたりしても、不正な二重処理が起きないようにすることを意味する。そのため、トークンが既に最大使用回数に達していないか、または特定のユーザーに一度使用されたトークンが別のユーザーによって再利用されていないかなどを、データベースで確認することが不可欠だ。

これらの処理は、データベーストランザクション内で実行することで、データの一貫性と整合性を保つ。具体的には、トークンのレコードをSELECT ... FOR UPDATEというSQL文でロックし、そのレコードの有効性（有効期限、使用回数）を確認し、使用回数をインクリメントし、使用したユーザーIDを記録する。そして、ユーザーの会話状態をリセットし、最後に目的のアクションを実行する。これらのステップが全て成功すればコミットし、途中でエラーが発生した場合はロールバックすることで、データベースが不整合な状態になるのを防ぐ。

プロダクション環境でディープリンクを運用する際には、いくつかのセキュリティと信頼性に関する考慮事項がある。第一に、Telegramメッセージ内でHTML形式で動的なコンテンツをレンダリングする際は、必ずhtmlspecialchars関数などを用いてコンテンツをサニタイズ（無害化）することだ。データベースから取得した名前やタイトルに特殊文字が含まれていると、TelegramのHTMLパーサーがエラーを起こし、メッセージが送信できなくなる可能性がある。第二に、Telegram APIとの通信は、ネットワーク障害やAPIのレート制限（アクセスが多すぎると一時的に制限されること）を考慮して設計する必要がある。cURLのタイムアウトを設定し、APIからのHTTPステータスコードやJSONレスポンスを厳密にチェックし、エラー発生時には適切にログを記録し、再試行のメカニズムを検討することも重要だ。第三に、未使用のまま期限切れになったトークンや、役目を終えたリンクデータがデータベースに蓄積されるのを防ぐため、定期的に古いトークンを削除またはアーカイブするメンテナンススクリプトを実行すべきだ。これにより、データベースのパフォーマンスを維持できる。