トラブルシューティング

このページでは、X Chat の暗号化と Chat XDK に固有の問題(鍵、セキュアキーバックアップ、復号/検証、および暗号化された送信ペイロードの構築)を扱います。 Webhook、OAuth、HTTP ステータスコード、レート制限については、一般の X API および認証のドキュメントを使用してください。

鍵とセキュアキーバックアップ

アンロックに失敗する(無効なパスコード)

パスコードが setup で使用したものと一致していることを確認してください
試行の間に待機してください。レルムは誤答をレート制限し、失敗が多すぎると復元をロックすることがあります

try:
    chat.unlock(passcode)
except ValueError as e:
    print(e)  # may mention InvalidPin or guesses remaining

try {
  await chat.unlock(passcode);
} catch (e) {
  console.error((e as Error).message);
}

chat.unlock(passcode_bytes).await?;

if err := chat.Unlock(passcode, juiceboxConfigJSON); err != nil {
    log.Println(err)
}

try { chat.Unlock(passcode, juiceboxConfigJson); }
catch (Exception e) { Console.WriteLine(e.Message); }

try { chat.unlock(passcode, juiceboxConfigJson); }
catch (Exception e) { System.out.println(e.getMessage()); }

鍵やアイデンティティがセットされていないため暗号化/復号が失敗する

まず秘密鍵をロードし、次にセッションアイデンティティを設定してください——あなたのユーザー ID と、X 上のレコードの public_key_version です。encrypt_* および prepare_* メソッドはこれで署名します。セッションアイデンティティなし(かつ明示的な呼び出し単位のオーバーライドもなし)でこれらを呼び出すとエラーになります。

chat.unlock(passcode)  # or: chat.import_keys(blob)
chat.set_identity(my_user_id, signing_key_version)

await chat.unlock(passcode);
chat.setIdentity(myUserId, signingKeyVersion);

chat.import_keys(&blob)?;
chat.set_identity(&my_user_id, &signing_key_version);

blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
_ = chat.ImportKeys(blob)
_ = chat.SetIdentity(myUserID, signingKeyVersion)

chat.ImportKeys(blobBytes);
chat.SetIdentity(myUserId, signingKeyVersion);

chat.importKeys(blobBytes);
chat.setIdentity(myUserId, signingKeyVersion);

ローカルの公開鍵がアカウントに登録されている鍵と一致しない

クライアントはしばしば 「このデバイス上の鍵は、このアカウントに登録されている鍵のいずれかに一致するか?」 に答える必要があります——復元やインポート後に、正しい public_key_version を採用するため、あるいはオンボーディングがすでに完了しているかを判定するためです。Chat XDK の get_public_keys の出力を API の public_key フィールドと文字列として比較すると、同じ鍵であっても常に失敗します。両者が異なるエンコーディングを使っているからです:

API は登録時にアップロードされたそのままの形で鍵を保存・返却します:DER (SPKI) エンコーディング——固定のアルゴリズム識別子プレフィックスの後ろに生の鍵が続きます
Chat XDK の get_public_keys は、そのプレフィックスなしで生の鍵のみを返します

同じ鍵、2 つの表記です。比較するには、両方を base64 デコードし、API のバイト列が SDK のバイト列で終わっていることを確認してください(両方が同じエンコーディングを保持しているケースに備えて、完全一致もマッチとみなします):

import base64

def same_key(local_b64: str, server_b64: str) -> bool:
    local = base64.b64decode(local_b64)    # chat.get_public_keys()["identity"]
    server = base64.b64decode(server_b64)  # API row's "public_key"
    return local == server or (len(server) > len(local) and server.endswith(local))

const sameKey = (localB64: string, serverB64: string): boolean => {
  const local = Buffer.from(localB64, 'base64');   // chat.getPublicKeys().identity
  const server = Buffer.from(serverB64, 'base64'); // API row's public_key
  return local.equals(server) ||
    (server.length > local.length && server.subarray(server.length - local.length).equals(local));
};

fn same_key(local: &[u8], server: &[u8]) -> bool {
    local == server || (server.len() > local.len() && server.ends_with(local))
}

func sameKey(local, server []byte) bool {
    return bytes.Equal(local, server) ||
        (len(server) > len(local) && bytes.HasSuffix(server, local))
}

static bool SameKey(byte[] local, byte[] server) =>
    local.SequenceEqual(server) ||
    (server.Length > local.Length &&
     server.AsSpan(server.Length - local.Length).SequenceEqual(local));

static boolean sameKey(byte[] local, byte[] server) {
    if (Arrays.equals(local, server)) return true;
    if (server.length <= local.length) return false;
    byte[] tail = Arrays.copyOfRange(server, server.length - local.length, server.length);
    return Arrays.equals(tail, local);
}

一致したら、その行の public_key_version を set_identity に採用してください。バージョンを比較するとき(たとえば最新の鍵を選ぶ場合)は、数値として比較してください——バージョンは長さがまちまちなミリ秒のタイムスタンプなので、辞書式比較では誤った値が選ばれます。

メッセージに対する会話鍵が見つからない

Message encrypted with key version '…' but no matching key found のようなエラーは、そのメッセージの conversation_key_version に対応する生の鍵を持っていないことを意味します。

conversation_key_change_event(ライブイベント)または meta.conversation_key_events(履歴)の鍵素材を extract_conversation_keys で復号する、あるいはそれらのブロブを decrypt_events に含める。set_cache_keys(true) が有効なら、decrypt_events は各会話の最新の検証済み鍵も保持するため、以後の decrypt_event や encrypt_* の呼び出しでは省略できます
そのバージョンに対して会話鍵が追加されており、まだ参加者であることを確認してください(はじめにを参照)

ピアに公開鍵がない

ピアがオンボードを完了していない可能性があります。登録後、API リファレンス → Encryption keys から public_key、signing_public_key、identity_public_key_signature、public_key_version をロードしてください。

復号と署名

復号に失敗する

生の会話鍵が古い/誤っている、または鍵バージョンが間違っている
encoded_event 文字列が不完全である
イベントタイプが復号可能なコンテンツとして扱える暗号化メッセージではない

署名が検証されない

検証はデフォルトで失敗クローズです(reject_unverified = true):SDK は検証されていない署名付きイベントを既に拒否しているため、ここで失敗した場合は、チェックを有効にする必要があるのではなく、検証入力が誤っていることを意味します。よくある原因:

送信者の署名鍵エントリが欠落または不完全(Chat XDK が必要とするすべてのフィールド——Chat XDK リファレンスを参照)
呼び出しに署名鍵が渡されておらず、set_signing_keys で保存されているものもない
送信者がバージョンをローテーションした——公開鍵を再取得してください
許容フロアより下の鍵バージョンは決して検証されません
グループの鍵変更イベントでは、署名者がすでにグループを離脱している場合、その鍵はもはや提供されません——離脱したメンバーによる鍵変更を参照してください

set_reject_unverified セッターは、このデフォルトからオプトアウトするために存在します(false。推奨されません)。以前に無効にした場合は、失敗クローズのデフォルトに戻してください。

chat.set_reject_unverified(True)

chat.setRejectUnverified(true);

chat.set_reject_unverified(true);

chat.SetRejectUnverified(true)

chat.SetRejectUnverified(true);

chat.setRejectUnverified(true);

返信に `reply_preview_validation: "Invalid"` が付いている

復号された返信は reply_preview_validation("Valid" / "Invalid"。JavaScript は 'valid' / 'invalid')を持つことがあります。Invalid は、メッセージ内の引用プレビューが埋め込まれた署名済みオリジナルイベントと一致しないことを意味します——引用は信頼できないものとして扱い、検証済みオリジナルからのみ引用内容を描画してください。メッセージ自体は別途検証されており、依然として本物です。プレビューが無効でも何もスローされません。

古いイベントが恒久的に検証に失敗する

signature missing or no matching signing key や、古いイベントでの ECDSA 不一致のようなエラーは恒久的です。署名は不変であり、イベント自体から署名済みペイロードを再構築することで検証されます。そのため、異なるバイトに署名された(あるいはまったく署名されていない)イベントは、以後のロードでも毎回失敗します——リトライ、鍵の更新、API 呼び出しでは修復できません。これらのイベントはリトライ可能なエラーではなく tombstone として扱ってください。会話鍵をローテーションすれば、そこから先はクリーンで検証可能な履歴が始まります。新しいメッセージは影響を受けません。

送信ペイロードの構築

これらのミスは X Chat 暗号化に固有です(一般的な HTTP エラーではありません):

問題	修正
鍵バイトが誤っている	API からの暗号化された鍵文字列ではなく、生の会話鍵バイトを Chat XDK に渡してください
JSON フィールド名が誤っている	`encrypted_content` → `encoded_message_create_event`、`encoded_event_signature` → `encoded_message_event_signature` をマップしてください
メッセージ ID が誤っている	返されたペイロードの `message_id` を送信してください——SDK が生成し署名済みイベントに埋め込むため、他の値では失敗します。リトライ時は同じ暗号化ペイロードを再利用して、ID が二度発行されないようにしてください
バージョン不一致	使用する鍵と `conversation_key_version` を揃え、`set_identity` に渡す署名鍵バージョンを public-key レコードに揃えてください
パス ID の形式	URL パスは依然としてハイフン付き会話 ID(`:` → `-`)が必要ですが、署名について SDK は任意の形式を受け付けます:`A:B`、`A-B`(順不同)、または裸の受信者ユーザー ID——すべて同じ署名バイトに正規化されます

状態を変更する呼び出しで API が 400 を返す

状態を変更するすべてのチャット呼び出し(会話鍵の追加やローテーション、グループの作成、メンバーの追加)は、リクエストボディに action_signatures を必要とし、API 境界で検証されます。エントリが欠落または不正な形式(それぞれに message_id、encoded_message_event_detail、および signature、public_key_version、signature_version を持つ message_event_signature が必要)の場合、直ちに HTTP 400 problem-details レスポンスを返します。SDK の prepare メソッド(prepare_conversation_key_change、prepare_group_create、prepare_group_members_change)を使い、返されたすべての署名を送信してください——グループ作成とメンバー追加は 2 つ返します。

メディアの暗号化と復号

添付を参照するメッセージと同じ会話鍵(およびバージョン)を使用してください
ダウンロードレスポンスは、decrypt_stream を実行するまで暗号文として扱ってください
MIME タイプは復号後に推測してください。ダウンロードの Content-Type は多くの場合、実際の画像タイプではありません

詳細:メディア。

安全なデバッグ

暗号化の失敗を調査する際は:

会話 ID、イベント ID、鍵のバージョンのみをログに出力してください
平文、パスコード、秘密鍵、完全な鍵ブロブはログに出力しないでください
set_identity に渡した署名鍵バージョンが public-key レコードの public_key_version と一致することを確認してください
履歴が不完全な場合は、鍵変更メタデータがスキップされないよう、復号前にすべてのイベントページをページングしてください

Getting Started

Products

Fundamentals

Partners & Customers

Resources

トラブルシューティング

鍵とセキュアキーバックアップ

アンロックに失敗する(無効なパスコード)

鍵やアイデンティティがセットされていないため暗号化/復号が失敗する

ローカルの公開鍵がアカウントに登録されている鍵と一致しない

メッセージに対する会話鍵が見つからない

ピアに公開鍵がない

復号と署名

復号に失敗する

署名が検証されない

返信に `reply_preview_validation: "Invalid"` が付いている

古いイベントが恒久的に検証に失敗する

送信ペイロードの構築

状態を変更する呼び出しで API が 400 を返す

メディアの暗号化と復号

安全なデバッグ

​鍵とセキュアキーバックアップ

​アンロックに失敗する(無効なパスコード)

​鍵やアイデンティティがセットされていないため暗号化/復号が失敗する

​ローカルの公開鍵がアカウントに登録されている鍵と一致しない

​メッセージに対する会話鍵が見つからない

​ピアに公開鍵がない

​復号と署名

​復号に失敗する

​署名が検証されない

​返信に reply_preview_validation: "Invalid" が付いている

​古いイベントが恒久的に検証に失敗する

​送信ペイロードの構築

​状態を変更する呼び出しで API が 400 を返す

​メディアの暗号化と復号

​安全なデバッグ

鍵とセキュアキーバックアップ

アンロックに失敗する(無効なパスコード)

鍵やアイデンティティがセットされていないため暗号化/復号が失敗する

ローカルの公開鍵がアカウントに登録されている鍵と一致しない

メッセージに対する会話鍵が見つからない

ピアに公開鍵がない

復号と署名

復号に失敗する

署名が検証されない

返信に `reply_preview_validation: "Invalid"` が付いている

古いイベントが恒久的に検証に失敗する

送信ペイロードの構築

状態を変更する呼び出しで API が 400 を返す

メディアの暗号化と復号

安全なデバッグ