Chat XDK リファレンス

Chat XDK は、X Chat の鍵管理、暗号化、復号、および署名を処理します。X の HTTP API は呼び出しません — Python または TypeScript の XDK、あるいは HTTPS とユーザーアクセストークンと組み合わせて使用してください。アプリのウォークスルー: Getting Started。サンプルボット: chat-xdk/examples。

インストール

pip install chatxdk

PyPI パッケージは chatxdk です。chat_xdk としてインポートします。Python 3.10+ が必要です。

npm install @xdevplatform/chat-xdk
npm install juicebox-sdk   # optional peer dependency — required for setup()/unlock() secure key backup

コンパイル済みの WASM エンジンはパッケージに同梱されています。ビルド手順は不要です。Node.js 18+ が必要です。

[dependencies]
# chat-xdk-core is not yet on crates.io — use the git dependency.
# It exports both ChatCore and the async secure-key-backup Chat type.
chat-xdk-core = { git = "https://github.com/xdevplatform/chat-xdk", tag = "v0.2.1" }

# Required until thrift 0.24 is released on crates.io
[patch.crates-io]
thrift = { git = "https://github.com/apache/thrift.git", rev = "deb36fa409849de45973b04ffc3ce49d277ca90a" }

go get github.com/xdevplatform/chat-xdk/go/chatxdk

プリコンパイル済みの静的ライブラリが含まれています（macOS arm64/amd64、Linux amd64 glibc/musl）。C コンパイラは必要ですが、Rust は不要です。Go 1.21+ が必要です。

dotnet add package XDevPlatform.ChatXdk

パッケージは自己完結型です。macOS（arm64、x64）、Linux（x64）、Windows（x64）用のネイティブライブラリが同梱されています。.NET 8+ が必要です。

<dependency>
  <groupId>com.x</groupId>
  <artifactId>chatxdk</artifactId>
  <version>0.2.1</version>
</dependency>

Maven Central で入手できます。jar には macOS（arm64、x64）、Linux（x64）、Windows（x64）用のネイティブライブラリが同梱されており、jna.library.path の設定は不要です。com.x.chatxdk からインポートします。JDK 17+ が必要です。

クイックスタート

バックログを復号し、鍵をキャッシュし、1 つのイベントを復号し、返信を暗号化します。Getting Started のように、送信ボディを POST /2/chat/conversations/{id}/messages に接続します。

from chat_xdk import Chat

chat = Chat(juicebox_config_json)  # or Chat() + import_keys(blob)
chat.unlock("YOUR_PASSCODE")
chat.set_key_version(signing_key_version)

result = chat.decrypt_events(raw_events, signing_keys)
for dm in result["messages"]:
    ev = dm["event"]
    if ev.get("type") == "Message":
        print(ev.get("sender_id"), ev.get("content", {}).get("text"))

cached = result["conversation_keys"]["keys"]
event = chat.decrypt_event(one_event_b64, cached, sender_signing_keys)

raw_key = cached[result["conversation_keys"]["latest_version"]]
payload = chat.encrypt_message(
    message_id, sender_id, conversation_id, raw_key, "Hi!",
    conversation_key_version, signing_key_version,
)

import { createChat } from '@xdevplatform/chat-xdk';

const chat = await createChat({
  juiceboxConfig: juiceboxConfigJson,
  getAuthToken: async (realmId) => getRealmToken(realmId),
});
await chat.unlock('YOUR_PASSCODE');
chat.setKeyVersion(signingKeyVersion);

const result = chat.decryptEvents(rawEvents, signingKeys);
for (const dm of result.messages) {
  if (dm.event.type === 'message') {
    console.log(dm.event.senderId, dm.event.content?.text);
  }
}

const cached = result.conversationKeys.keys;
const event = chat.decryptEvent(oneEventB64, cached, senderSigningKeys);

const rawKey = cached[result.conversationKeys.latestVersion!];
const payload = chat.encryptMessage({
  messageId, senderId, conversationId, conversationKey: rawKey, text: 'Hi!',
  conversationKeyVersion, signingKeyVersion,
});

// ChatCore + import_keys, or chat_xdk_core::Chat + unlock().await
let result = chat.decrypt_events(&raw_events, &signing_keys);
let cached = &result.conversation_keys.keys;
let event = chat.decrypt_event(one_event_b64, cached, &sender_signing_keys)?;
// cached values are XChatConversationKey; encrypt_message wants owned bytes
let latest = result.conversation_keys.latest_version.as_deref().unwrap_or_default();
let conv_key = cached[latest].to_bytes();
let payload = chat.encrypt_message(EncryptMessageParams::new(
    &message_id, &sender_id, &conversation_id, conv_key, "Hi!",
    &conversation_key_version, &signing_key_version,
))?;

chat := chatxdk.New()
defer chat.Close()
blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
_ = chat.ImportKeys(blob)
chat.SetKeyVersion(signingKeyVersion)

result, err := chat.DecryptEvents(rawEvents, signingKeys)
cached := result.ConversationKeys.Keys
event, err := chat.DecryptEvent(oneEventB64, cached, senderSigningKeys)
rawKey := cached[*result.ConversationKeys.LatestVersion]
payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
    MessageID: messageID, SenderID: senderID, ConversationID: conversationID,
    ConversationKey: rawKey, Text: "Hi!",
    ConversationKeyVersion: conversationKeyVersion, SigningKeyVersion: signingKeyVersion,
})
_ = event
_ = payload
_ = err

using var chat = new Chat();
chat.ImportKeys(privateKeyBytes);
chat.SetKeyVersion(signingKeyVersion);

var result = chat.DecryptEvents(rawEvents, signingKeys);
var cached = result.ConversationKeys.Keys;
var evt = chat.DecryptEvent(oneEventB64, cached, senderSigningKeys);
var payload = chat.EncryptMessage(new EncryptMessageParams {
    MessageId = messageId, SenderId = senderId, ConversationId = conversationId,
    ConversationKey = rawKey, Text = "Hi!",
    ConversationKeyVersion = conversationKeyVersion, SigningKeyVersion = signingKeyVersion,
});

try (Chat chat = new Chat()) {
    chat.importKeys(privateKeyBytes);
    chat.setKeyVersion(signingKeyVersion);

    DecryptEventsResult result = chat.decryptEvents(rawEvents, signingKeys);
    Map<String, byte[]> cached = result.conversationKeys.keys;
    JsonNode event = chat.decryptEvent(oneEventB64, cached, senderSigningKeys);

    EncryptMessageParams params = new EncryptMessageParams();
    params.messageId = messageId;
    params.senderId = senderId;
    params.conversationId = conversationId;
    params.conversationKey = rawKey;
    params.text = "Hi!";
    params.conversationKeyVersion = conversationKeyVersion;
    params.signingKeyVersion = signingKeyVersion;
    SendPayload payload = chat.encryptMessage(params);
}

ライフサイクルと鍵

SDK を構築し、秘密鍵を保存し（パスコード保護された安全な鍵バックアップまたはローカル鍵 blob）、公開鍵を Chat API に登録し、アンロックまたはインポート後に登録済みの公開鍵バージョンを設定します。安全な鍵バックアップは Juicebox で実装されており、関連する設定フィールドがその名前を持つのはこのためです。デバイス/アプリ ID ごとに generate_keypairs を 1 回呼び出します；登録ペイロードを公開鍵エンドポイントに投稿します。すべてのバインディングで安全な鍵バックアップには setup / unlock（および関連するパスコードヘルパー）を使用します。export_keys / import_keys（ボットとサーバー用の未加工鍵 blob 永続化）は、ネイティブバインディングのみ — Python、Go、.NET、JVM、Rust — で利用できます。JS/WASM バインディングは未加工の鍵のエクスポートやインポートを公開しません: ブラウザではインスタンスに到達するスクリプトは identity を流出できるため、JS は鍵を安全な鍵バックアップ内に保持します。リクエストごとのバックアップ realm ラウンドトリップを避けたい JS サーバーは、リクエスト間で 1 つのアンロック済み Chat インスタンスを再利用するか、鍵 blob がサポートされているネイティブバインディングを実行するべきです。

from chat_xdk import Chat

# Secure key backup (client)
chat = Chat(juicebox_config_json)
chat.setup("YOUR_PASSCODE")          # first time — generates keypairs
# chat.unlock("YOUR_PASSCODE")        # later sessions
chat.set_key_version(version)    # from add-public-key / get-public-keys response
reg = chat.get_public_keys()     # or registration fields from generate_keypairs

# Key blob (server / bot)
chat2 = Chat()
chat2.import_keys(secret_blob)
chat2.set_key_version(version)
blob = chat2.export_keys()       # treat as a password

import { createChat } from '@xdevplatform/chat-xdk';

const chat = await createChat({
  juiceboxConfig: juiceboxConfigJson,
  getAuthToken: async (realmId) => getRealmToken(realmId),
});
await chat.setup('YOUR_PASSCODE');
// await chat.unlock('YOUR_PASSCODE');
chat.setKeyVersion(version);
const publics = chat.getPublicKeys();

// JS/WASM stores keys only through secure key backup — there is no raw key
// export/import here. For key-blob persistence, use a native binding.

// chat_xdk_core::Chat — async secure key backup unlock, or ChatCore + import_keys
chat.setup("YOUR_PASSCODE").await?;
// chat.unlock("YOUR_PASSCODE").await?;
chat.set_key_version(&version);
let publics = chat.get_public_keys()?;
let blob = chat.export_keys()?;
chat.import_keys(&blob)?;

chat := chatxdk.New()
defer chat.Close()

// Prefer ImportKeys for servers; secure key backup unlock where supported
keyBlob, _ := chatxdk.Base64ToBytes(privateKeysB64)
if err := chat.ImportKeys(keyBlob); err != nil {
    log.Fatal(err)
}
chat.SetKeyVersion(version)
publics, err := chat.GetPublicKeys()
blob, err := chat.ExportKeys()
_ = publics
_ = blob
_ = err

using var chat = new Chat();
chat.ImportKeys(privateKeyBytes);
// or secure key backup setup / unlock when config is available
chat.SetKeyVersion(version);
var publics = chat.GetPublicKeys();
var blob = chat.ExportKeys();

try (Chat chat = new Chat()) {
    chat.importKeys(privateKeyBytes);
    chat.setKeyVersion(version);
    var publics = chat.getPublicKeys();
    byte[] blob = chat.exportKeys();
}

安全な鍵バックアップ設定は 3 つの形を受け付けます: X API の juicebox_config オブジェクト（推奨 — そのまま渡す）、完全な sdk_config ラッパー、または裸の token_map。オプション: 署名検証はデフォルトで有効（reject_unverified = true）— 無効にするには set_reject_unverified(false) を呼び出します（推奨されません）；バックアップ realm 設定が変更された場合は update_config；UI 状態には is_unlocked / has_identity_key。完全なフィールドリストは chat-xdk リポジトリのスタブにあります。

会話鍵

3 つの prepare メソッドは、それぞれ 1 回の呼び出しで鍵変更に必要なすべて（新しい会話鍵の生成、渡された公開鍵からすべての参加者向けに暗号化、変更への署名）を行います。すべて同じ PreparedConversationChange 形を返し、POST の準備が整います — SDK フィールドの encrypted_key を conversation_participant_keys の中で encrypted_conversation_key に名前を変え、アクション署名を必須の action_signatures ボディフィールドにマップしてください。

シナリオ	メソッド	返されるアクション署名
1:1 を開始（会話 ID を省略 — SDK が導出）または任意の会話の鍵をローテーション（ID を渡す）	`prepare_conversation_key_change`	1
グループの作成（`POST /2/chat/conversations/group/initialize` によって発行される ID）	`prepare_group_create`	2 — 両方送信
グループへのメンバー追加	`prepare_group_members_change`	2 — 両方送信

未加工の鍵バイトを encrypt_message およびメディア用に保持してください；API の暗号化エンベロープを encrypt に渡してはいけません。

ラップする前に取得した鍵を検証してください。 prepare メソッドは、渡された任意の公開鍵に対して新しい会話鍵を暗号化します。渡す前に、各取得済みレコードに対して verify_key_binding(identity, signing, signature) を呼び出してください — public-keys API のレコードの public_key、signing_public_key、identity_public_key_signature フィールド — 置き換えられた identity 鍵が会話鍵を受け取れないようにするためです。

鍵変更イベントペイロードで extract_conversation_keys を使い、{ keys, latest_version } を再構築します。decrypt_conversation_key は単一の ECIES blob をアンラップします。

# One entry per participant public key, from the public-keys API:
# participants = [
#     {"user_id": "1215441834412953600", "public_key": "BASE64_IDENTITY_PUBLIC_KEY", "key_version": "1733889755256"},
#     {"user_id": "1843439638876491776", "public_key": "BASE64_IDENTITY_PUBLIC_KEY", "key_version": "1766181805686"},
# ]
prepared = chat.prepare_conversation_key_change(my_user_id, signing_key_version, participants)
# prepared["conversation_key"]   — raw bytes for encrypt_message
# prepared["participant_keys"]   — per-user wraps; rename encrypted_key → encrypted_conversation_key on POST
# prepared["action_signatures"]  — required on the POST body

extracted = chat.extract_conversation_keys(key_change_blobs)
keys = extracted["keys"]
latest = extracted["latest_version"]
raw = keys[latest]

one = chat.decrypt_conversation_key(encrypted_blob)

const prepared = chat.prepareConversationKeyChange({
  senderId: myUserId, signingKeyVersion, publicKeys: participants,
});
// prepared.conversationKey — Uint8Array for encryptMessage
// prepared.participantKeys / prepared.actionSignatures — POST body fields

const extracted = chat.extractConversationKeys(keyChangeBlobs);
const raw = extracted.keys[extracted.latestVersion!];

const one = chat.decryptConversationKey(encryptedBlob);

let prepared = chat.prepare_conversation_key_change(
    ConversationKeyChangeParams::new(&my_user_id, &signing_key_version, participants),
)?;
let extracted = chat.extract_conversation_keys(&key_change_blobs);
let latest = extracted.latest_version.as_deref().unwrap_or_default();
let raw = &extracted.keys[latest];
let one = chat.decrypt_conversation_key(&encrypted_blob)?;

prepared, err := chat.PrepareConversationKeyChange(chatxdk.ConversationKeyChangeParams{
    SenderID: myUserID, SigningKeyVersion: signingKeyVersion, PublicKeys: participants,
})
// prepared.ConversationKey feeds EncryptMessage
// prepared.ParticipantKeys / prepared.ActionSignatures — POST body fields
extracted, err := chat.ExtractConversationKeys(keyChangeBlobs)
one, err := chat.DecryptConversationKey(encryptedBlob)
_ = prepared
_ = extracted
_ = one
_ = err

var prepared = chat.PrepareConversationKeyChange(new ConversationKeyChangeParams {
    SenderId = myUserId, SigningKeyVersion = signingKeyVersion, PublicKeys = participants,
});
var extracted = chat.ExtractConversationKeys(keyChangeBlobs);
var raw = extracted.Keys[extracted.LatestVersion];
var one = chat.DecryptConversationKey(encryptedBlob);

ConversationKeyChangeParams keyParams = new ConversationKeyChangeParams();
keyParams.senderId = myUserId;
keyParams.signingKeyVersion = signingKeyVersion;
keyParams.publicKeys = participants;
PreparedConversationChange prepared = chat.prepareConversationKeyChange(keyParams);
ConversationKeyBundle extracted = chat.extractConversationKeys(keyChangeBlobs);
byte[] raw = extracted.keys.get(extracted.latestVersion);
byte[] one = chat.decryptConversationKey(encryptedBlob);

グループの作成とメンバー追加については、各メソッドが必要とするパラメータを渡します（prepare_group_create にはメンバー/管理者 ID リスト；prepare_group_members_change には新規プラス現在のロスター） — サンプルは Groups を参照してください。両方とも2 つのアクション署名を返します；POST には両方含める必要があります。

復号

decrypt_events は履歴とバックログ用です: ストリームから会話鍵を取り出し、復号済みメッセージを返し、バッチ全体を失敗させる代わりにイベントごとのエラーを収集します。decrypt_event は、鍵キャッシュをすでに持っている場合の単一のライブイベント用です。失敗時に raise/throw します。送信者を SDK が検証できるように署名鍵を渡します。API の公開鍵フィールドを SigningKeyEntry にマップします: public_key_version → public_key_version（同じ名前）、signing_public_key → public_key、public_key → identity_public_key、加えて identity_public_key_signature と user_id。検証はデフォルトで必須です: 空の署名鍵リストを省略または渡してもスキップされません — 署名付きイベントは失敗します（decrypt_events では errors に収集され、decrypt_event ではスローされます）。実際に検証をスキップするには、まず set_reject_unverified(false) を呼び出す必要があります（本番環境では推奨されません）。

signing_keys = [{
    "user_id": uid,
    "public_key_version": row["public_key_version"],
    "public_key": row["signing_public_key"],
    "identity_public_key": row["public_key"],
    "identity_public_key_signature": row["identity_public_key_signature"],
} for row in api_public_keys]

result = chat.decrypt_events(raw_events, signing_keys)
for idx, msg in (result.get("errors") or {}).items():
    log.warning("event %s failed: %s", idx, msg)
for dm in result["messages"]:
    ev = dm["event"]
    if ev.get("type") == "Message":
        text = ev.get("content", {}).get("text")

cached = result["conversation_keys"]["keys"]
live = chat.decrypt_event(one_event_b64, cached, signing_keys_for_sender)

const signingKeys = apiPublicKeys.map((row) => ({
  userId: uid,
  publicKeyVersion: row.public_key_version,
  publicKey: row.signing_public_key,
  identityPublicKey: row.public_key,
  identityPublicKeySignature: row.identity_public_key_signature,
}));

const result = chat.decryptEvents(rawEvents, signingKeys);
for (const [idx, msg] of Object.entries(result.errors ?? {})) {
  console.warn(`event ${idx} failed: ${msg}`);
}
const cached = result.conversationKeys.keys;
const live = chat.decryptEvent(oneEventB64, cached, signingKeysForSender);

let result = chat.decrypt_events(&raw_events, &signing_keys);
for (idx, msg) in &result.errors {
    eprintln!("event {idx} failed: {msg}");
}
let cached = &result.conversation_keys.keys;
let live = chat.decrypt_event(one_event_b64, cached, &signing_keys_for_sender)?;

result, err := chat.DecryptEvents(rawEvents, signingKeys)
for idx, msg := range result.Errors {
    log.Printf("event %s failed: %s", idx, msg)
}
cached := result.ConversationKeys.Keys
live, err := chat.DecryptEvent(oneEventB64, cached, signingKeysForSender)
_ = live
_ = err

var result = chat.DecryptEvents(rawEvents, signingKeys);
foreach (var kv in result.Errors) { /* kv.Key = event index, kv.Value = error */ }
var cached = result.ConversationKeys.Keys;
var live = chat.DecryptEvent(oneEventB64, cached, signingKeysForSender);

DecryptEventsResult result = chat.decryptEvents(rawEvents, signingKeys);
Map<String, byte[]> cached = result.conversationKeys.keys;
JsonNode live = chat.decryptEvent(oneEventB64, cached, signingKeysForSender);

暗号化と送信ヘルパー

encrypt_message は、テキストメッセージ用の署名済み暗号文を構築します（オプションの entities、media_hash_key 経由の attachments、TTL、通知フラグ）。返されたペイロードを送信メッセージボディにマップします: encrypted_content → encoded_message_create_event、encoded_event_signature → encoded_message_event_signature、および message_id。返信とリアクション（sequence_id は親をターゲットにします）には、encrypt_reply、encrypt_add_reaction、および encrypt_remove_reaction を使用します。encrypt / decrypt は、会話鍵の下での UTF-8 メタデータ（たとえば暗号化されたグループ名）用です — メッセージエンベロープ用ではありません。encrypt_stream / decrypt_stream は添付バイトを暗号化します；Media を参照してください。低レベルの sign / verify / verify_key_binding は高度なフローをサポートします；会話鍵の変更、グループの作成、およびメンバーの追加は prepare メソッドによって署名されます。 encrypt_message / encrypt_reply に渡す会話 ID は、保持している任意の形式で構いません — イベントからの A:B、リストや URL パスからの A-B（どちらの順序でも）、または受信者のユーザー ID だけ — SDK は署名する前に正規化します。グループ ID（g プレフィックス付き）はそのまま渡されます。

payload = chat.encrypt_message(
    message_id, sender_id, conversation_id, raw_conversation_key, "Hello",
    conversation_key_version, signing_key_version,
    # Optional keyword args: entities, attachments, should_notify, ttl_msec
)
body = {
    "message_id": message_id,
    "encoded_message_create_event": payload["encrypted_content"],
    "encoded_message_event_signature": payload["encoded_event_signature"],
}
# POST body to /2/chat/conversations/{id}/messages

reply = chat.encrypt_reply(
    reply_message_id, sender_id, conversation_id, raw_conversation_key,
    "Sounds good", conversation_key_version, signing_key_version,
    parent_sequence_id,  # reply_to_sequence_id — the message being replied to
)
name_ct = chat.encrypt("Group title", raw_conversation_key)
title = chat.decrypt(name_ct, raw_conversation_key)

const payload = chat.encryptMessage({
  messageId, senderId, conversationId, conversationKey: rawConversationKey, text: 'Hello',
  conversationKeyVersion, signingKeyVersion,
});
const body = {
  message_id: messageId,
  encoded_message_create_event: payload.encryptedContent,
  encoded_message_event_signature: payload.encodedEventSignature,
};

const reply = chat.encryptReply({
  messageId: replyMessageId, senderId, conversationId, conversationKey: rawConversationKey,
  text: 'Sounds good', conversationKeyVersion, signingKeyVersion,
  replyToSequenceId: parentSequenceId, // the message being replied to
});
const nameCt = chat.encrypt('Group title', rawConversationKey);
const title = chat.decrypt(nameCt, rawConversationKey);

// conv_key: XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
let payload = chat.encrypt_message(EncryptMessageParams::new(
    &message_id, &sender_id, &conversation_id, conv_key.to_bytes(), "Hello",
    &conversation_key_version, &signing_key_version,
))?;
// Map payload fields into the send-message JSON body as above
let name_ct = chat.encrypt("Group title", &conv_key)?;
let title = chat.decrypt(&name_ct, &conv_key)?;

payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
    MessageID: messageID, SenderID: senderID, ConversationID: conversationID,
    ConversationKey: rawKey, Text: "Hello",
    ConversationKeyVersion: conversationKeyVersion, SigningKeyVersion: signingKeyVersion,
})
// body: message_id, encoded_message_create_event, encoded_message_event_signature
nameCt, err := chat.Encrypt("Group title", rawKey)
title, err := chat.Decrypt(nameCt, rawKey)
_ = payload
_ = title
_ = err

var payload = chat.EncryptMessage(new EncryptMessageParams {
    MessageId = messageId, SenderId = senderId, ConversationId = conversationId,
    ConversationKey = rawKey, Text = "Hello",
    ConversationKeyVersion = conversationKeyVersion, SigningKeyVersion = signingKeyVersion,
});
// Map EncryptedContent / EncodedEventSignature into the send-message body
var nameCt = chat.Encrypt("Group title", rawKey);
var title = chat.Decrypt(nameCt, rawKey);

EncryptMessageParams params = new EncryptMessageParams();
params.messageId = messageId;
params.senderId = senderId;
params.conversationId = conversationId;
params.conversationKey = rawKey;
params.text = "Hello";
params.conversationKeyVersion = conversationKeyVersion;
params.signingKeyVersion = signingKeyVersion;
SendPayload payload = chat.encryptMessage(params);
// Map to encoded_message_create_event / encoded_message_event_signature on POST

String nameCt = chat.encrypt("Group title", rawKey);
String title = chat.decrypt(nameCt, rawKey);

メディアストリーム

テキストに使用されたものと同じ会話鍵でファイルバイトを暗号化し、Chat メディア API 経由でアップロードし、encrypt_message で media_hash_key を添付します。これは Posts メディアモデル（expansions=attachments.media_keys）ではありません。完全なアップロード/ダウンロードフロー: Media。

ciphertext = chat.encrypt_stream(file_bytes, raw_conversation_key)
# Upload `ciphertext`; the `media_hash_key` you attach on encrypt_message
# comes from the media-upload finalize step, not from encrypt_stream.

plain = chat.decrypt_stream(ciphertext, raw_conversation_key)

const ciphertext = chat.encryptStream(fileBytes, rawConversationKey);
// Upload `ciphertext`; mediaHashKey comes from the upload finalize step.
const plain = chat.decryptStream(ciphertext, rawConversationKey);

// conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
let ciphertext = chat.encrypt_stream(&file_bytes, &conv_key)?;
let plain = chat.decrypt_stream(&ciphertext, &conv_key)?;

ciphertext, err := chat.EncryptStream(fileBytes, rawKey)
plain, err := chat.DecryptStream(ciphertext, rawKey)
_ = plain
_ = err

var ciphertext = chat.EncryptStream(fileBytes, rawKey);
var plain = chat.DecryptStream(ciphertext, rawKey);

byte[] ciphertext = chat.encryptStream(fileBytes, rawKey);
byte[] plain = chat.decryptStream(ciphertext, rawKey);

大きなメディア向けのインクリメンタルストリーミング

大きなファイルの場合、ペイロード全体をメモリに保持しないでください: stream_encryptor() / stream_decryptor() は、StreamEncryptor / StreamDecryptor を返します。push(chunk) でチャンク（約 1 MB ずつ）を供給し、最後に finish() を 1 回呼び出します。復号では、finish() は切り詰められたストリームを検出します（最終フレームより前に入力が終わった場合は失敗します）ので、成功するまでプッシュされた平文を完全なものとして扱わないでください。

JS/WASM のみ: finish() は基になる WASM オブジェクトを消費して解放します — finish() の後には決して free() を呼び出さないでください（例外がスローされます）。free() は、finish の前にストリームを放棄する場合（たとえばエラーパス）にのみ呼び出してください。

Python
TypeScript

enc = chat.stream_encryptor(raw_conversation_key)
chunks = [enc.push(chunk) for chunk in read_in_chunks(file_bytes, 1 << 20)]
chunks.append(enc.finish())
ciphertext = b"".join(chunks)

dec = chat.stream_decryptor(raw_conversation_key)
out = [dec.push(chunk) for chunk in read_in_chunks(ciphertext, 1 << 20)]
out.append(dec.finish())  # raises on truncation
plain = b"".join(out)

const enc = chat.streamEncryptor(rawConversationKey);
const parts: Uint8Array[] = [];
try {
  for (const chunk of readInChunks(fileBytes, 1 << 20)) parts.push(enc.push(chunk));
  parts.push(enc.finish()); // consumes + frees enc — do not call enc.free() after this
} catch (e) {
  enc.free(); // only when abandoning before finish()
  throw e;
}
const ciphertext = concat(parts);

ユーティリティ

Base64/hex ヘルパー、MIME スニッフィング、および画像寸法は、モジュールレベルの関数（Python/JS/Rust/Go）または ChatXdkUtilities（C#/Java）として利用できます — 追加のライブラリを取り込まずに添付メタデータを構築するときに便利です。

from chat_xdk import (
    bytes_to_base64, base64_to_bytes, bytes_to_hex, hex_to_bytes,
    detect_mime_type, detect_image_dimensions,
)

b64 = bytes_to_base64(raw)
raw2 = base64_to_bytes(b64)
hexed = bytes_to_hex(raw)
raw3 = hex_to_bytes(hexed)
mime = detect_mime_type(file_bytes)
w, h = detect_image_dimensions(file_bytes)

import { bytesToBase64, base64ToBytes, bytesToHex, hexToBytes, detectMimeType, detectImageDimensions } from '@xdevplatform/chat-xdk';

const b64 = bytesToBase64(raw);
const raw2 = base64ToBytes(b64);
const hexed = bytesToHex(raw);
const raw3 = hexToBytes(hexed);
const mime = detectMimeType(fileBytes);
const dims = detectImageDimensions(fileBytes);
const width = dims?.width ?? 0;
const height = dims?.height ?? 0;

let b64 = chat_xdk_core::bytes_to_base64(&raw);
let raw2 = chat_xdk_core::base64_to_bytes(&b64)?;
let hexed = chat_xdk_core::bytes_to_hex(&raw);
let raw3 = chat_xdk_core::hex_to_bytes(&hexed);
let mime = chat_xdk_core::detect_mime_type(&file_bytes);
let dims = chat_xdk_core::detect_image_dimensions(&file_bytes);
let (w, h) = dims.map(|d| (d.width, d.height)).unwrap_or((0, 0));

b64, _ := chatxdk.BytesToBase64(raw)
raw2, err := chatxdk.Base64ToBytes(b64)
hexed, err := chatxdk.BytesToHex(raw)
raw3, err := chatxdk.HexToBytes(hexed)
mime, _ := chatxdk.DetectMimeType(fileBytes)
dims, _ := chatxdk.DetectImageDimensions(fileBytes)
w, h := dims.Width, dims.Height
_ = b64
_ = raw2
_ = hexed
_ = raw3
_ = mime
_ = w
_ = h
_ = err

var b64 = ChatXdkUtilities.BytesToBase64(raw);
var raw2 = ChatXdkUtilities.Base64ToBytes(b64);
var hexed = ChatXdkUtilities.BytesToHex(raw);
var raw3 = ChatXdkUtilities.HexToBytes(hexed);
var mime = ChatXdkUtilities.DetectMimeType(fileBytes);
var dims = ChatXdkUtilities.DetectImageDimensions(fileBytes);
var w = dims?.Width ?? 0;
var h = dims?.Height ?? 0;

String b64 = ChatXdkUtilities.bytesToBase64(raw);
byte[] raw2 = ChatXdkUtilities.base64ToBytes(b64);
String hexed = ChatXdkUtilities.bytesToHex(raw);
byte[] raw3 = ChatXdkUtilities.hexToBytes(hexed);
String mime = ChatXdkUtilities.detectMimeType(fileBytes);
ImageDimensions wh = ChatXdkUtilities.detectImageDimensions(fileBytes);
long width = wh.width, height = wh.height;

重要な型

これらの概念的な型は、複数の言語にわたって現れます（正確なフィールド名は異なります；JS では message のように camelCase のイベント識別子を使うことが多いです）:

SendPayload — encrypt_message および関連する暗号化ヘルパーの戻り値；Chat API 送信ボディにマップします。
PublicKeyRegistrationPayload — add-public-key API 用の generate_keypairs / 公開鍵ゲッターの出力。
SigningKeyEntry — 署名検証のために decrypt に渡される送信者の公開素材。
PreparedConversationChange — 3 つの prepare メソッドの出力: 導出されたまたは渡された conversation_id、未加工の conversation_key バイト、conversation_key_version、participant_keys（user_id、encrypted_key、public_key_version）、および action_signatures（message_id、encoded_message_event_detail、signature、signature_version、public_key_version、オプションの signature_payload — そのペイロードが平文の鍵を埋め込むため鍵変更署名では省略されます）。
DecryptEventsResult — メッセージ、オプションのエラー、抽出された conversation_keys。

完全なフィールドリストについては、chat-xdk リポジトリの言語スタブ（docs/API.md、*.pyi、index.d.ts）を使用してください。

エラー

Python は通常、記述的なメッセージ（たとえば無効なパスコード）で ValueError を発生させます。TypeScript/JavaScript は Error をスローします。Go は (value, error) を返します。履歴には decrypt_events を優先してください、そうすれば 1 つの不良イベントがバッチを中止しません；部分的な失敗については errors コレクションを検査してください。一部の検証エラーは恒久的です。署名は不変であり、イベント自体から署名済みペイロードを再構築することで検証されるため、signature missing or no matching signing key または ECDSA の不一致で失敗する古いイベントは、将来のすべてのロードで失敗します — 再試行、鍵の更新、または API 呼び出しでは治せません。これらは一時的なエラーではなく、トゥームストーンとして扱ってください。会話鍵をローテーションすると、その時点からクリーンで検証可能な履歴が始まります。

次のステップ

Getting Started

Chat XDK を Chat API に接続する

Media

ストリーム暗号化とメディア REST

Real-time events

Webhook とアクティビティ配信

Troubleshooting

よくある失敗

​インストール

​クイックスタート

​ライフサイクルと鍵

​会話鍵

​復号

​暗号化と送信ヘルパー

​メディアストリーム

​大きなメディア向けのインクリメンタルストリーミング

​ユーティリティ

​重要な型

​エラー

​次のステップ

Getting Started

Media

Real-time events

Troubleshooting

インストール

クイックスタート

ライフサイクルと鍵

会話鍵

復号

暗号化と送信ヘルパー

メディアストリーム

大きなメディア向けのインクリメンタルストリーミング

ユーティリティ

重要な型

エラー

次のステップ