punchline

エンドツーエンド暗号化されたピアツーピアチャット（UDP経由）。アカウント不要、中央サーバーによるメッセージの中継・保存なし、中間者なし。単なる2つのピア、直接接続、Noiseプロトコル暗号化。

https://github.com/user-attachments/assets/939e96d3-45e3-4484-9a27-28c3a0457b05

目次

• 機能概要
• クイックスタート
• 仕組み
• CLIリファレンス
• 使い方
  • 設定
  • ピアの管理
  • ステータス確認
  • サーバーオプション
  • テーマ設定
  • シェル補完
• 暗号
  • IKハンドシェイク
  • イニシエーターの決定
  • 鍵の保存
• ワイヤプロトコル
  • ホールパンチプロトコル
  • トランスポートプロトコル
  • シグナルプロトコル
  • STUNプロトコル
• プロジェクト構成
• インストール
  • crates.ioから
  • ソースからビルド
• テストの実行
• 技術スタック
• ライセンス

機能概要

2人のユーザーが各自のマシンで punchline connect <peer> を実行します。PunchlineはNATを通過し、暗号化ハンドシェイクを実行し、プライベートチャットを開始します。所要時間はわずか数ミリ秒。内蔵のSTUNサーバーとシグナルサーバーが発見を処理した後、その後の通信には関与しません。

クイックスタート

cargo build --release

サーバーの起動（両方のピアから到達可能なマシン上で）。または、私が公開しているサーバー（64.225.107.28、STUN: ポート 3478、シグナリング: ポート 8743）を使用することもできます。

punchline-stund                  # STUNサーバー - ピアに自身の公開IPを通知
punchline-signald                # シグナルサーバー - 通信したいピアをマッチング

各ピアのマシンで:

# 自身のID（X25519鍵ペア）を生成
punchline keygen

# 公開鍵を相手と共有
punchline pubkey

# 相手の鍵を保存
punchline peers add alice a1b2c3d4...64_hex_chars

# 接続（両方のピアがこのコマンドを実行し、互いを指定）
punchline connect alice --stun <server>:3478 --signal <server>:8743

TUIが起動し、接続進行状況がリアルタイムで表示されます。

1. STUN探索 - punchline-stund 経由で自分の外部アドレスを解決

2. シグナルサーバー - punchline-signald に接続

3. ピア待ち - シグナルサーバーが両ピアをマッチング

4. ホールパンチ - 直接UDP経路を確立

5. Noiseハンドシェイク - 暗号化鍵交換

   

完了後、チャット画面になります。文字を入力してEnterキーを押して送信。Escキーで終了します。

仕組み

システム全体は3つのバイナリで構成され、すべてこのリポジトリに含まれています。

初期セットアップ後、STUNサーバーとシグナルサーバーには再アクセスしません。すべての通信は直接ピアツーピアで行われます。

CLIリファレンス

punchline

グローバルフラグ:

punchline-stund

punchline-signald

使い方

設定

毎回 --stun と --signal を指定する代わりに、~/.config/punchline/config.toml を作成します。

stun_server = "203.0.113.10:3478"
signal_server = "203.0.113.10:8743"

ピアの管理

punchline peers                              # 一覧表示
punchline peers add alice a1b2c3d4...        # 追加
punchline peers remove alice                 # 削除

エイリアスは ~/.punchline/known_peers.toml に保存されます。生の64文字の16進鍵を直接指定して接続することもできます。

ステータス確認

punchline status

自身のID、設定、サーバー到達可能性（実際のSTUNプローブとTCP接続を送信）、ピア数を表示します。

サーバーオプション

両サーバーとも -v（デバッグ）、-vv（トレース）、-q（クワイエット）、--address、--port をサポートします。

punchline-stund -v --port 3478
punchline-signald -v --port 8743

テーマ設定

~/.config/punchline/style.toml でTUIをカスタマイズできます。 動画で使用したスタイル:

[colors]
my_text = "#ebdbb2"
peer_text = "#bdae93"
input_text = "#ebdbb2"
border = "#ebdbb2"
sidebar_key = "#ebdbb2"
sidebar_value = "#bdae93"

[padding]
chat_horizontal = 2
chat_vertical = 1

すべての色は16進RGBです。ファイルがない場合は、端末のデフォルト色が使用されます。

シェル補完

punchline completions bash > ~/.local/share/bash-completion/completions/punchline
punchline completions zsh > ~/.zfunc/_punchline
punchline completions fish > ~/.config/fish/completions/punchline.fish

暗号

完全なプロトコル名: Noise_IK_25519_ChaChaPoly_SHA256

IKハンドシェイク

IKパターンでは、イニシエーターはハンドシェイク開始前にレスポンダーの静的公開鍵を知っている。両ピアはすでに互いの鍵を保持している（帯域外またはピアレジストリで交換済み）ため、初回接続時の信頼（TOFU）は不要。

1. イニシエーター -> レスポンダー: イニシエーターの静的公開鍵を含む暗号化メッセージを、レスポンダーの既知の鍵で暗号化して送信。受動的監視者に対するID秘匿を提供。
2. レスポンダー -> イニシエーター: 復号・検証し、返信。両サイドは共有セッション鍵でトランスポートモードに移行。

イニシエーターの決定

Punchlineは、各ピアの公開鍵の先頭8バイトをビッグエンディアンの u64 として比較し、決定論的にイニシエーターを選択します。値が小さい方がイニシエーターになります。両サイドが独立にこの計算を行います。

鍵の保存

IDは32バイトのX25519秘密鍵で、~/.punchline/id_x25519 にUnixパーミッション 0600 で保存されます。公開鍵は読み込み時に導出されます。鍵生成は x25519-dalek と OsRng を使用します。

ワイヤプロトコル

各UDPパケットの先頭バイトがタイプを識別します。

ホールパンチプロトコル

両方のピアが同時に同じアルゴリズムを実行します。

1. 200msごとに相手の外部アドレスに PROBE（0x00）を送信。
2. PROBE を受信したら、ACK（0x01）の送信に切り替え。
3. ACK を受信したら、最後の ACK を1回送信し、成功を宣言。
4. セーフティタイムアウト: ACKを2秒間送信しても応答がない場合、相手は完了したとみなす。

トランスポートプロトコル

メッセージ（0x02）はNoise暗号化されたUTF-8ペイロードを運びます。キープアライブ（0x03）は暗号化された空ペイロードで、10秒ごとに送信され、暗号ノンスの同期を維持します。30秒間パケットがないと切断されます。

シグナルプロトコル

WebSocket上のJSON:

// PairRequest (クライアント -> サーバー)
{ "external_addr": "203.0.113.5:48291", "public_key": "a1b2...", "target_public_key": "d4e5..." }

// PairResponse (サーバー -> クライアント)
{ "target_external_addr": "198.51.100.7:51003", "target_public_key": "d4e5..." }

STUNプロトコル

RFC 5389（簡略版）に従います: バインディング要求/応答、XOR-MAPPED-ADDRESS。IPv4のみ。

プロジェクト構成

4つのクレートからなるCargoワークスペース:

crates/
├── proto/      # 共有ライブラリ: 暗号、STUN、シグナルタイプ、トランスポートトレイト
├── client/     # P2Pクライアント: CLI、TUI、接続ロジック、ピア管理
├── signald/    # シグナルサーバー: WebSocketピアマッチング
└── stund/      # STUNサーバー: 外部アドレス探索

インストール

crates.ioから

cargo install punchline           # TUIクライアント
cargo install punchline-signald   # シグナルサーバー
cargo install punchline-stund     # STUNサーバー

ソースからビルド

前提条件: Rust 2024エディション（rustc 1.85以上）

git clone https://github.com/michal-pielka/punchline.git
cd punchline
cargo build --release

バイナリは target/release/ に配置されます:

• punchline
• punchline-signald
• punchline-stund

テストの実行

cargo test

テストは暗号操作、STUNエンコード/デコード、シグナルプロトコルシリアライゼーション、設定解析、ピア管理、スタイルテーマ、Noise IKハンドシェイクをカバーします。

技術スタック

ライセンス

MIT - LICENSE を参照してください。