⚠️ WORK IN PROGRESS — NOT PRODUCTION READY ⚠️

🚧 This project is under active development. 🚧
🛡️ Security layer (OMEMO / end-to-end encryption) is coming soon. 🛡️
❌ Do not use this SDK in production yet. ❌
🔒 Without the security layer, communications are NOT encrypted and are unsafe for real-world use.

---

KmpXMPP

Kotlin Multiplatform XMPP SDK for Android, iOS, and JVM/Desktop, with modular RFC/XEP support and Docker-backed interop tests.

Install (No BOM)

KmpXMPP is published as separate modules. Add only what you use.

dependencies {
    implementation("io.github.androidpoet:kmpxmpp-core:0.1.0-alpha01")
    implementation("io.github.androidpoet:kmpxmpp-client:0.1.0-alpha01")
    implementation("io.github.androidpoet:kmpxmpp-im:0.1.0-alpha01")
    implementation("io.github.androidpoet:kmpxmpp-websocket:0.1.0-alpha01")

    // Optional XEPs:
    implementation("io.github.androidpoet:kmpxmpp-xep-0184-receipts:0.1.0-alpha01")
    implementation("io.github.androidpoet:kmpxmpp-xep-0333-chat-markers:0.1.0-alpha01")
    implementation("io.github.androidpoet:kmpxmpp-xep-0085-chat-states:0.1.0-alpha01")
}

Module Structure

• Core/runtime: kmpxmpp-core, kmpxmpp-client, kmpxmpp-stream, kmpxmpp-transport, kmpxmpp-xml
• Security/auth: kmpxmpp-security, kmpxmpp-sasl, kmpxmpp-sm, kmpxmpp-reconnect
• Transports: kmpxmpp-websocket (KMP/Ktor), kmpxmpp-tcp (JVM TCP adapter)
• IM/features: kmpxmpp-im, kmpxmpp-xep-* extension modules
• OMEMO track: kmpxmpp-omemo-core, kmpxmpp-omemo-persistence-sqlite, kmpxmpp-xep-0384-omemo
• Testing/sample: kmpxmpp-interop-tests, kmpxmpp-sample-whatsapp-jvm

Quick Start

import io.github.androidpoet.kmpxmpp.client.DefaultKmpXmppClient
import io.github.androidpoet.kmpxmpp.core.Jid
import io.github.androidpoet.kmpxmpp.core.onFailure
import io.github.androidpoet.kmpxmpp.core.onSuccess
import io.github.androidpoet.kmpxmpp.im.DefaultXmppMessageService
import io.github.androidpoet.kmpxmpp.stream.XmppSessionConfig
import io.github.androidpoet.kmpxmpp.stream.XmppSessionOrchestrator
import io.github.androidpoet.kmpxmpp.websocket.createWebSocketXmppTransport
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    val host = "chat.example.com"
    val port = 443
    val me = Jid(local = "alice", domain = host, resource = "android")
    val peer = Jid(local = "bob", domain = host)

    // For production keep secure=true and tlsInitiallyActive=true.
    val transport = createWebSocketXmppTransport(path = "/xmpp-websocket", secure = true)
    val orchestrator = XmppSessionOrchestrator(
        config = XmppSessionConfig(
            host = host,
            port = port,
            tlsInitiallyActive = true,
        ),
        transport = transport,
    )
    val client = DefaultKmpXmppClient(streamEngine = orchestrator, transport = transport)
    val chat = DefaultXmppMessageService(client)

    client.connect()
        .onFailure { error("connect failed: ${it.message}") }

    client.authenticate(me, "strong-password")
        .onFailure { error("auth failed: ${it.message}") }

    chat.sendChatMessage(peer, "hello from kmpxmpp")
        .onFailure { error("send failed: ${it.message}") }
        .onSuccess { println("message sent to ${peer.asBareJid()}") }

    client.disconnect()
        .onFailure { error("disconnect failed: ${it.message}") }
}

Run + Verify

Build:

./gradlew build

Docker-backed interop:

KMPXMPP_RUN_DOCKER_E2E=true ./gradlew :kmpxmpp-interop-tests:jvmDockerE2e

Full release gate:

./gradlew productionVerify --no-daemon --stacktrace

Sample WhatsApp-style desktop flow:

./gradlew :kmpxmpp-sample-whatsapp-jvm:run

Platform Notes

• Android/iOS should use kmpxmpp-websocket (Ktor-based KMP transport).
• kmpxmpp-tcp is a JVM transport adapter and not required for mobile-only apps.
• TLS is required by default; plain auth without TLS is blocked unless explicitly enabled.

Typed Feature Policy

kmpxmpp-core includes typed feature IDs and policy gates:

• XmppFeatureId
• XmppFeaturePolicy (StableOnly, AllowExperimental, AllowDeferred, AllowDeprecated, AllowAll)
• XmppCapabilityRegistry
• XmppFeatureCatalog

Use StableOnly in production to avoid accidental activation of non-stable modules.

Production Readiness (Current Boundary)

• Ready baseline: core chat flows, presence, receipts/markers/states, Docker interop verification.
• Not yet complete: fully audited OMEMO end-to-end crypto lifecycle/trust/session backup and restore claim.
• Recommendation: publish as alpha, keep OMEMO marked as evolving, and keep productionVerify required in CI.

Detailed checklist: docs/PRODUCTION_READINESS.md.

Contributing

Contributions are welcome! If you've found a bug, have an idea for an improvement, or want to contribute new features, please open an issue or submit a pull request.

Find this repository useful? ❤️

Support it by joining stargazers for this repository. ⭐
Also, follow me on GitHub for my next creations! 🤩

License

MIT © 2026 Ranbir Singh