Referencia del Chat XDK

El Chat XDK se encarga de la gestión de claves, cifrado, descifrado y firma para X Chat. No llama a la HTTP API de X—combínalo con el XDK de Python o TypeScript, o con HTTPS y un token de acceso de usuario. Recorrido de la app: Primeros pasos. Bots de ejemplo: chat-xdk/examples.

Instalar

pip install chatxdk

El paquete de PyPI es chatxdk; impórtalo como chat_xdk. Requiere Python 3.10+.

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

El motor WASM compilado viene dentro del paquete: no hay paso de build. Requiere 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

Se incluyen bibliotecas estáticas precompiladas (macOS arm64/amd64, Linux amd64 glibc/musl): necesitas un compilador de C, pero no Rust. Requiere Go 1.21+.

dotnet add package XDevPlatform.ChatXdk

El paquete es autónomo: incluye las bibliotecas nativas para macOS (arm64, x64), Linux (x64) y Windows (x64). Requiere .NET 8+.

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

Disponible en Maven Central. El jar incluye la biblioteca nativa para macOS (arm64, x64), Linux (x64) y Windows (x64): no necesitas configurar jna.library.path. Importa desde com.x.chatxdk. Requiere JDK 17+.

Inicio rápido

Descifra un backlog, cachea claves, descifra un evento y cifra una respuesta. Conecta el cuerpo de envío a POST /2/chat/conversations/{id}/messages como se explica en Primeros pasos.

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);
}

Ciclo de vida y claves

Construye el SDK, guarda las claves privadas (copia de seguridad segura de claves protegida con código de acceso o un blob de claves local), registra las claves públicas con la Chat API y establece tu versión de clave pública registrada después de unlock o import. La copia de seguridad segura de claves está implementada con Juicebox, y por eso los campos de configuración relacionados llevan ese nombre. Llama a generate_keypairs una vez por identidad de dispositivo/app; envía el payload de registro con POST al endpoint de claves públicas. Usa setup / unlock (y helpers de código de acceso relacionados) para la copia de seguridad segura de claves en cada binding. export_keys / import_keys (persistencia de blob de clave en bruto para bots y servidores) están disponibles solo en los bindings nativos—Python, Go, .NET, JVM y Rust. El binding JS/WASM no expone la exportación ni importación de claves en bruto: en un navegador cualquier script que acceda a la instancia podría exfiltrar la identidad, así que JS mantiene las claves dentro de la copia de seguridad segura de claves. Un servidor JS que quiera evitar un round-trip al realm de copia de seguridad por solicitud debería reutilizar una única instancia Chat desbloqueada entre solicitudes, o ejecutar un binding nativo donde se admitan blobs de clave.

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();
}

La configuración de la copia de seguridad segura de claves acepta tres formas: el objeto juicebox_config de la X API (recomendado—pasado verbatim), un wrapper completo sdk_config o un token_map desnudo. Opcional: la verificación de firma está activada por defecto (reject_unverified = true)—llama a set_reject_unverified(false) para desactivarla (no recomendado); update_config si cambia la configuración de realms de copia de seguridad; is_unlocked / has_identity_key para el estado de la UI. Las listas completas de campos están en los stubs del repo chat-xdk.

Claves de conversación

Tres métodos prepare hacen que una sola llamada haga todo lo que un cambio de clave necesita: generar una nueva clave de conversación, cifrarla para cada participante (a partir de las claves públicas que pases) y firmar el cambio. Todos devuelven la misma forma PreparedConversationChange, lista para POST—renombra el campo del SDK encrypted_key a encrypted_conversation_key en conversation_participant_keys y mapea las firmas de acción al campo de cuerpo requerido action_signatures.

Escenario	Método	Firmas de acción devueltas
Iniciar un 1:1 (omite el id de conversación—el SDK lo deriva) o rotar la clave de cualquier conversación (pasa el id)	`prepare_conversation_key_change`	1
Crear un grupo (id acuñado por `POST /2/chat/conversations/group/initialize`)	`prepare_group_create`	2—envía ambas
Agregar miembros a un grupo	`prepare_group_members_change`	2—envía ambas

Conserva los bytes de la clave en bruto para encrypt_message y multimedia; nunca pases el sobre cifrado de la API a encrypt.

Verifica las claves obtenidas antes de envolverlas. Los métodos prepare cifran la nueva clave de conversación hacia cualesquiera claves públicas que pases. Antes de pasarlas, llama a verify_key_binding(identity, signing, signature) en cada registro obtenido—sus campos public_key, signing_public_key e identity_public_key_signature de la API de claves públicas—para que una clave de identidad sustituida no pueda recibir la clave de conversación.

Usa extract_conversation_keys en los payloads de eventos de cambio de clave para reconstruir { keys, latest_version }. decrypt_conversation_key desenvuelve un solo blob ECIES.

# 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);

Para crear grupo y agregar miembros, pasa los params que cada método necesita (listas de ids de miembros/admins para prepare_group_create; nuevos más el roster actual para prepare_group_members_change)—consulta Grupos para ejemplos. Ambos devuelven dos firmas de acción; el POST debe incluir ambas.

Descifrar

decrypt_events es para el historial y el backlog: extrae las claves de conversación del stream, devuelve los mensajes descifrados y recolecta errores por evento en lugar de fallar el lote completo. decrypt_event es para un solo evento en vivo cuando ya tienes un caché de claves; lanza excepción/throw ante un fallo. Pasa claves de firma para que el SDK pueda verificar a los remitentes. Mapea los campos de clave pública de la API a SigningKeyEntry: public_key_version → public_key_version (mismo nombre), signing_public_key → public_key, public_key → identity_public_key, más identity_public_key_signature y user_id. La verificación es obligatoria por defecto: omitir o pasar una lista vacía de claves de firma no la salta—los eventos firmados fallan (recolectados en errors para decrypt_events, lanzados para decrypt_event). Para realmente saltar la verificación primero debes llamar a set_reject_unverified(false) (no recomendado en producción).

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);

Helpers de cifrado y envío

encrypt_message construye el texto cifrado firmado para un mensaje de texto (entidades opcionales, adjuntos vía media_hash_key, TTL, flags de notificación). Mapea el payload devuelto al cuerpo send-message: encrypted_content → encoded_message_create_event, encoded_event_signature → encoded_message_event_signature, más tu message_id. Usa encrypt_reply, encrypt_add_reaction y encrypt_remove_reaction para respuestas y reacciones (sequence_id apunta al padre). encrypt / decrypt son para metadatos UTF-8 bajo la clave de conversación (por ejemplo, un nombre de grupo cifrado)—no sobres de mensajes. encrypt_stream / decrypt_stream cifran los bytes de los adjuntos; consulta Multimedia. Los métodos de bajo nivel sign / verify / verify_key_binding admiten flujos avanzados; los cambios de clave de conversación, creaciones de grupo y adiciones de miembros son firmados por los métodos prepare. El id de conversación pasado a encrypt_message / encrypt_reply puede ser cualquier forma que tengas—A:B de eventos, A-B de listados o rutas URL (en cualquier orden) o solo el id de usuario del destinatario—el SDK lo canonicaliza antes de firmar. Los ids de grupo (con prefijo g) pasan sin cambios.

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);

Streams de multimedia

Cifra los bytes del archivo con la misma clave de conversación usada para el texto, sube mediante las APIs de multimedia de Chat y adjunta media_hash_key en encrypt_message. Este no es el modelo de multimedia de Posts (expansions=attachments.media_keys). Flujo completo de subida/descarga: Multimedia.

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);

Streaming incremental para multimedia grande

Para archivos grandes, evita mantener el payload completo en memoria: stream_encryptor() / stream_decryptor() devuelven un StreamEncryptor / StreamDecryptor al que alimentas por chunks (unos 1 MB cada uno) con push(chunk), y luego llamas a finish() una vez al final. Al descifrar, finish() detecta un stream truncado (falla si la entrada terminó antes del frame final), así que no trates el texto plano acumulado como completo hasta que tenga éxito.

Solo JS/WASM: finish() consume y libera el objeto WASM subyacente—nunca llames a free() después de finish() (lanza error). Llama a free() solo para abandonar un stream antes de finalizar (por ejemplo, en una ruta de error).

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);

Utilidades

Los helpers de Base64/hex, sniffing de MIME y dimensiones de imagen están disponibles como funciones a nivel de módulo (Python/JS/Rust/Go) o ChatXdkUtilities (C#/Java)—útiles al construir metadatos de adjuntos sin traer librerías adicionales.

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;

Tipos importantes

Estos tipos conceptuales aparecen en varios lenguajes (los nombres exactos de los campos difieren; JS suele usar discriminadores de evento en camelCase como message):

SendPayload — valor de retorno de encrypt_message y helpers de cifrado relacionados; mapea al cuerpo de envío de la Chat API.
PublicKeyRegistrationPayload — salida de generate_keypairs / getters de claves públicas para la API add-public-key.
SigningKeyEntry — material público del remitente pasado a decrypt para la verificación de firma.
PreparedConversationChange — salida de los tres métodos prepare: el conversation_id derivado o pasado, los bytes de conversation_key en bruto, conversation_key_version, participant_keys (user_id, encrypted_key, public_key_version) y action_signatures (message_id, encoded_message_event_detail, signature, signature_version, public_key_version, signature_payload opcional—omitido en firmas de cambio de clave porque ese payload incrusta la clave en texto plano).
DecryptEventsResult — mensajes, errores opcionales y conversation_keys extraídas.

Para listas completas de campos, usa los stubs de lenguaje en el repo chat-xdk (docs/API.md, *.pyi, index.d.ts).

Errores

Python normalmente lanza ValueError con un mensaje descriptivo (por ejemplo, un código de acceso inválido). TypeScript/JavaScript lanza Error. Go devuelve (value, error). Prefiere decrypt_events para el historial de modo que un evento defectuoso no aborte el lote; inspecciona la colección de errores para ver fallos parciales. Algunos errores de verificación son permanentes. Las firmas son inmutables y se verifican reconstruyendo el payload firmado desde el evento en sí, así que un evento antiguo que falla con signature missing or no matching signing key o un desajuste ECDSA fallará en cada carga futura—ninguna reintentación, actualización de claves o llamada a la API puede sanarlo. Trátalos como tombstones, no como errores transitorios. Rotar la clave de conversación inicia un historial limpio y verificable desde ese punto en adelante.

Próximos pasos

Primeros pasos

Conecta el Chat XDK a la Chat API

Multimedia

Cifrado por stream y REST de multimedia

Eventos en tiempo real

Webhooks y entrega de actividad

Solución de problemas

Fallos comunes

​Instalar

​Inicio rápido

​Ciclo de vida y claves

​Claves de conversación

​Descifrar

​Helpers de cifrado y envío

​Streams de multimedia

​Streaming incremental para multimedia grande

​Utilidades

​Tipos importantes

​Errores

​Próximos pasos

Primeros pasos

Multimedia

Eventos en tiempo real

Solución de problemas

Instalar

Inicio rápido

Ciclo de vida y claves

Claves de conversación

Descifrar

Helpers de cifrado y envío

Streams de multimedia

Streaming incremental para multimedia grande

Utilidades

Tipos importantes

Errores

Próximos pasos