機能と制限事項

デザインリファレンス：2026年10月26日。主なユースケースは、接続されたアカウントからアクセス可能な Telegramのプライベートグループおよびチャンネルです。本ドキュメントでは、 実装済みの動作、プラットフォームの制限、および今後の課題を区別しています。目標アーキテクチャの 項目は、その機能がすでに存在することを示すものではありません。

スタンドアロンアプリケーション#

TgWitnessには、独自のインストール手順、データディレクトリ、およびリリースライフサイクルがあります。同梱の Webインターフェースでは、設定や確認を行うことができ、エクスポートされた記録は単独でも利用可能です。

利用者は自身のアカウントを連携させ、各アカウントで表示可能な情報源を選択することで、 保存された観測ジャーナルを取得します。パネルには、コンテンツ、保存された変更内容、観測の 出所、および既知の欠落情報が表示されます。別の調査員が、エクスポートされた資料を検証することができます。

重要なのは、4つの異なる状態です。アカウントの認証、情報源へのアクセス、正常に動作する コレクター、そして配信の完全性がどの程度確立されているか、という4点です。最初の 3つの状態のいずれも、4つ目の状態を自動的に証明するものではありません。グループが静かであるからといって、必ずしも コレクターが機能していないとは限りません。

共同調査#

管理者は、ワークスペースや 個々のチャットを対象としたアクセストークンを発行でき、7つの権限、IP制限、有効期限、ログイン制限、 およびセッション制御を設定できます。読み取り専用のレビュー担当者は、 Telegramの認証やメインパネルのキーを受け取ることなく、案件を閲覧できます。 チャット限定のアクセス権限は、 アカウント全体の設定やジャーナル全体のエクスポートとは独立して管理されます。

自動MTProxyは、4つの公開ソースまたは オペレーターカタログから、Telegramの有効なルートを維持します。IPモードによって、 障害発生時に別のプロキシを待機するか、明示的に許可された直接ルートを使用できるかが決定されます。 外部HTTPリクエストには、個別のルートと無効化スイッチが用意されています。

アーカイブツール#

最新のmainでは、履歴の取得、アーカイブの検索と分析、 読み取り専用MCP、ローカルでのOCR/文字起こし、および 送信用Webhookが追加されました。これらはソースコードからチェックアウトして利用可能な機能であり、 0.7.0ポータブルプレビュー版以降に追加されたものです。分析レポートおよび認識されたテキストは、 キャプチャされたイベントとは別々に管理されます。

オプション機能#

基本的な設定手順は、「アカウント」→「ソース」→「監視」の順です。「エクストラ」は独立した設定項目であり、 TelegramのWitnessボットとGitHubのキャプチャプレビューが含まれます。各項目では、設定画面を表示する前に、 利用可能状況と要件が明示されます。カードを選択すると手順が表示されますが、これにより登録やサービスの開始が行われるわけではありません。

ボットのセットアップは、読み取り専用アクセス権の作成、公開設定の選択、そして Witnessホストでの起動という3つのステップで構成されます。ネットワークおよび公開オプション、既存の接続、 検証コマンドは、必要に応じて開示されます。 ダウンロードされた設定は、 実行中のWitnessとは別個のものです。追加機能の切り替えを行っても下書きは保持されますが、アカウントの変更やロックを行うと、 一時トークンとフォームがクリアされます。組み込みのガイドには起動手順が含まれています。 GitHub Actionsは、あなたの フォークからピン留めされたコレクターを起動し、1つのチャットをキャプチャして、ワークフローの来歴を含む暗号化されたハンドオフを生成します。

プロトコルおよび非公開の情報源#

MTProtoはTelegramのプロトコルであり、TelethonはTgWitnessがMTProtoと 通信するために使用するPythonライブラリです。これらは別々の接続方法ではありません。「Collection」はMTProtoを使用し、 オプションの「witness」はBot APIを通じて署名付きチェックを公開します。

各ワークスペースには、独自の認証済みクライアントとアカウント更新ストリームがあります。TgWitnessは、 設定されたソースから観測データを選択し、履歴のスナップショットやメディアのダウンロードなどの機能については、 個別に明示的なリクエストを行います。

非公開の情報源には、公開ユーザー名は必要ありません。Telegramのピアタイプと数値IDが 識別子となります。タイトルやユーザー名は変更される可能性があります。アクセスは、既存の メンバーシップおよび権限によって決まります。TgWitnessは、情報源に自動的に参加したり、 参加承認を迂回したりすることはありません。別のアカウントからのアクセスハッシュは、汎用的なアクセストークンではありません。

収集モデルでは、参加前の非公開履歴、参加者／管理者の 役割、セッションの失効、権限の削除または変更、グループからスーパーグループへの 移行、トピック／フォーラム、関連するディスカッション、チャンネルの識別情報、および利用できない 添付ファイルなどを考慮する必要があります。すべての組み合わせについて、実稼働環境での検証が完了しているわけではありません。

ソースの可視性は、コレクターの起動時に確認されます。範囲内の ダイアログ結果からソースが欠落している場合、それはアクセスが確認されていないことを意味し、削除が証明されたわけではありません。1つのソースが 利用できない場合でも、他のアクセス可能なソースの監視には支障がありません。招待 リンクや実際のセッションを、公開用フィクスチャに決して記載しないでください。

複数のアカウント#

このパネルは、任意の数のワークスペースに対応しており、各ワークスペースには以下の機能が備わっています：

• 認証、暗号化された保管庫、および接続経路。
• SQLiteジャーナルおよびEd25519署名用ID。
• 選択された情報源、メディアキュー、およびキャプチャ設定。
• 監視状態、エラー、チェックポイント、およびエクスポート機能。

表示されているワークスペースを切り替えても、別のコレクターの動作は停止しません。ワークスペースをまたいだアカウントの 重複認証は拒否されます。すでに1つのTelegram アカウントに紐付けられているジャーナルを別のアカウントに再割り当てすることはできませんが、同じアカウントへの再接続は可能です。 これにより、アカウントの識別情報および関連するメッセージIDの範囲が保持されます。

固定の処理数や測定されたスループットの保証はありません。ワークスペースは Pythonプロセスとイベントループを共有します。個別のアカウントワーカーの実装は今後の課題です。 現時点でのプロセス分離については、別々のインストール、ポート、データディレクトリをご利用ください。

各アカウントに、アクセス可能な情報源を割り当ててください。異なるアカウントが同じ グループを監視している場合でも、その監視データは個別に管理され、元の情報源が保持されます。1人のオペレーターが管理するマシン上の2つのアカウントは、 2つの独立した証人とはみなされません。エクスポートは ワークスペース単位で行われます。統合されたケースパッケージやグローバルなTelegramタイムラインの機能は実装されていません。

キャプチャと出典明記#

「Sources」では、新規メッセージ、編集、削除、リアクション、 およびメンバーシップについて、アカウントごとの設定切り替えが可能です。プリセットでは、すべてのカテゴリ、またはメッセージ／編集／削除のいずれかを保持します。 このポリシーはワークスペースで選択されたグループに適用され、再起動後も維持され、 変更前後のデータで署名されます。デフォルトではすべてのカテゴリが保持されます。 カテゴリを無効にしても 過去の記録は削除されません。また、再度有効にしても、記録されなかったイベントは復元されません。 運用記録、その他のグループサービスイベント、および明示的な履歴スナップショットは 別個に扱われます。キャプチャされたTelegramオブジェクトは、 個別の更新設定にかかわらず、埋め込まれたメタデータを保持する場合があります。現時点では、グループごとのカテゴリ上書き機能はありません。

ある行動が特定の人物に帰属するのは、情報源がその行為者を実際に明示している場合に限られます。 それ以外の場合、インターフェースは帰属情報の欠落を報告します。ユーザー名や氏名は 観察された属性であり、実世界の身元の証明ではありません。

容量とTelegramの制限#

品質を保証して監視できるチャットの数は、一概には言えません。 処理能力は、1秒あたりのピークイベント数、添付ファイルの量とサイズ、追加の RPC、アクティブなアカウント数、ディスクのレイテンシ／空き容量、ネットワーク状況、Telegramの制限、 許容可能な遅延、およびキューの深さによって異なります。

Telegramは、パッシブ配信とアクティブなショートポーリングを区別しています。その更新 ドキュメントでは、公開 チャンネル／スーパーグループに対する追加のupdates.getChannelDifference呼び出しについて説明しており、同時にショートポーリングを行う ソースは最大10件までとすることを推奨しています。これは、選択されたグループが10件に制限されるということでも、完全性が保証されるということでもありません。

FloodWaitを無視したり、追加アカウントからの容量を線形と仮定したりする ような、恣意的な高頻度ポーリングは、有効なサイジングモデルとは言えません。デフォルトの制限は、 リストされた最初の1,000件のダイアログ、履歴スナップショットあたり最大500件のメッセージ、 タイプごとに収集ファイルあたり1～2,000 MiB、および非圧縮の署名付きZIPコンテンツは4 GiBです。これらは 「パラメータ」でワークスペースごとに変更可能です。エクスポートには、イベント数の固定上限はありません。 ブラウザのフォールバックは、デフォルトで128 MiBに制限されています。ストリーミングCLIには設定可能な 転送制限があり、デフォルトは5 GiBです。

tools/check_capacity.pyは、ローカルでの合成データの取り込みおよびエクスポートを測定します。その結果は、 Telegramの配信測定値でも、実際のチャット数の保証でもありません。測定されたバージョンおよびワークロードについては、 VERIFICATION.mdをご参照ください。

信頼性と復旧#

実装されている機能には、SQLite WAL／同期トランザクション、メッセージ およびメディアジョブの原子的な書き込み、永続的なジョブと再試行の遅延、オリジナルバージョンの記述子、 再試行回数の制限；永続化されたメディアのFloodWait；テキストイベントの ネットワーク待機時間外でのメディアダウンロード；後続の書き込みが継続中の安定プレフィックスによるエクスポート；設定および 監査記録の原子性；ログイン置換失敗後の有効な認証情報の保持； 破損した追加ワークスペースの隔離；明示的な再接続試行；明確な 認証喪失の報告；および単調時計を用いた実時間変更検出などが含まれます。

アカウントおよびチャンネルの pts/qts/seq は保存され、再起動後も復元されます。また、監視対象のチャットは 定期的に再確認されます。証拠の形式については、こちらをご覧ください。位置情報を 定期的に保存することは、ジャーナルの受諾に対するアトミックかつロスレスな確認ではありません。

各プロセスの開始時には、前回のヘッドとオフライン境界が記録されます。現在の履歴は ギャップの修復として扱われません。Telegramの差分保持容量には限りがあり、 differenceTooLongでは消失したコンテンツのすべてを復元することはできません。復元不可能なギャップは、 後の履歴スナップショットが成功した場合でも、明示的に残しておく必要があります。

証拠モデル#

各イベントには、シーケンス、ローカルUTC観測時刻、提供されている場合は送信元時刻、 種類、送信元、提供されている場合はアクター、元のペイロード、前回のハッシュ、および署名が記録されます。 メッセージの観測データには、コレクターアカウントおよび実行コンテキストも保持されます。

署名付きプロセスレシートには、ランダムな実行ID、TgWitness/Python/OSの依存関係 バージョン、ソースファイルのSHA-256値および集約フィンガープリント、初期アカウント、 スコープおよび設定、UTC/単調な測定値、ならびに直前のジャーナルヘッダーが含まれます。 設定の変更、起動／停止、およびエラーは、同じジャーナルに記録されます。チェックポイントは、 起動時、監視中の5分ごと（変更可能）、および正常な停止時に保持されます。 保持されたローカルチェックポイントにより、以前のジャーナルプレフィックスへのロールバックを検出することが可能です。

RFC 3161に基づくリクエストの作成およびOpenSSLによるレスポンスの検証が実装されています。 自動送信機能は実装されていません。リクエストや、マシンの 時刻を含むローカル署名は、独立したタイムスタンプとはみなされません。TIMESTAMP.mdをご参照ください。

コレクターおよび署名鍵を管理するオペレーターは、新しい署名付き 観測データを捏造する可能性があります。署名は、Telegramでの発信元、真実性、または自動的な 法的証拠能力を立証するものではありません。より強固な証拠保全には、独立したチェックポイント／タイムスタンプの保存、 鍵へのアクセス制御、転送記録、および信頼できるソフトウェアによる検証が必要です。

エクスポート、導入、および引き継ぎ#

署名付きZIPファイルには、元のJSONL、CSV、HTML、保存された添付ファイル、ハッシュ、 署名付きマニフェスト、および利便性を考慮した検証ツールが含まれています。これは1つのワークスペースと、固定された完全な ジャーナルプレフィックスを対象としています。パネル検索フィルターによって、記録が黙って削除されることはありません。 秘密鍵、 トークン、およびTelegramのセッションは除外されますが、元の観測データには依然として 個人情報やTelegramのメタデータが含まれている可能性があります。

ZIPダイジェスト、信頼できるフィンガープリント、チェックポイント、処理受領記録、および引き継ぎ記録は、 それぞれ個別に保持してください。検証対象のZIPファイルに含まれているという理由だけで実行可能コードを信頼するのではなく、 信頼できる環境から取得した検証ツールを使用してください。

ブラウザインターフェースは、Node.js、CDN、外部フォントを必要とせず、ローカルで動作します。1つの オペレータートークンでインストールを制御します。リモートアクセスには、HTTPSまたはSSHトンネルが必要です。 ネイティブのPythonおよびコンテナ定義が提供されており、 deploy/ディレクトリ下にサービスの例が掲載されています。実行されたプラットフォームチェックは別途一覧化されています。

デフォルトのワークスペースはデータルートを使用します。追加のワークスペースはprofiles/<id>/を使用します。 バックアップを行うには、プロセスを停止させ、完全なデータおよび鍵セットが必要です。証拠用ZIPファイルは アプリケーションのバックアップではありません。シークレットについては、新しいデータ ディレクトリ用に外部のマスターキーを使用できます。ジャーナルおよびメディアの暗号化は、オペレーターのディスクまたはボリュームによって提供されます。 CONNECTION-SECURITY.md および OPERATIONS.md を参照してください。

安定版のリリース基準#

安定版がリリースされるまでは、次のように補足してください：

1. 実際のプライベートグループ、スーパーグループ、フォーラム、チャンネルにおいて、メンバー／管理者の役割や 非表示／表示の履歴（ログイン／2FA、権限の取り消し、アクセス権の喪失を含む）を記録します。
2. 既知の行動に対する、編集、削除、リアクション、メンバーシップ、およびメディアの監視を行います。
3. プロセスのクラッシュ／ホストのクラッシュ、ディスク障害／ディスク容量不足、有効期限切れのファイル参照、FloodWait、 ネットワーク切断、ファイルの破損、およびデータベースのロールバック。
4. 測定された遅延、キュー、メモリ、ディスク容量を考慮した、継続的なマルチアカウント利用。これには、 静的なソースと動的なソースの両方を併せて含みます。
5. MTProtoの状態遷移とジャーナルの受入の間に中断が生じました。
6. 対象のOS／コンテナ環境へのクリーンインストール、およびバックアップと復元の検証が行われています。
7. セキュリティ、署名、および帰属・証拠に関する主張についての独立した検証。

管理ログのポーリング、追加のリアクターリスト、優先度付きポーリング、個別のワーカー、 アプリケーション全体の暗号化については、今後の課題となります。範囲を限定したパネルへのアクセスについては、 「アクセスと権限」に記載されています。バージョン 0.6 では、 ACCOUNTS.md に記載されている、範囲を限定した単一アカウントの TData およびアカウントファイルのインポートに対応しています。 公開前にTelegram APIの利用規約をご確認ください。参考文献およびプラットフォームに関する 調査結果は、RESEARCH.mdに記載されています。