Standards-first Kotlin Multiplatform building blocks for WebAuthn and passkey integrations.

This project helps teams implement passwordless login without rebuilding the hardest parts from scratch. It gives you typed protocol models, strict validation, backend ceremony services, platform passkey clients, and optional transport/adaptation modules that stay close to the WebAuthn specification.

• WebAuthn is security-sensitive and protocol-heavy.
• Passkey products often need to share logic across backend, Android, and iOS.
• Kotlin teams usually want typed APIs, predictable validation, and flexible integration points instead of one monolithic SDK.

This repo focuses on those needs:

• Standards first: behavior is driven by WebAuthn L3 and related RFCs.
• Kotlin-first: KMP modules share the right logic instead of pushing everything into platform wrappers.
• Flexible integration: use only the modules you need, from pure model/validation all the way to Ktor routes and client transport helpers.
• Heavy lifting included: challenge/origin validation, authenticator-data parsing, signature verification boundaries, attestation policy hooks, and platform bridge logic are already here.

• A JVM/Ktor WebAuthn backend using typed ceremony services.
• Android and iOS passkey clients with shared Kotlin orchestration.
• A client/server setup that shares model and validation semantics instead of duplicating protocol assumptions.
• A modular stack where server, client, transport, storage, and attestation trust can be adopted separately.

WebAuthn has two ceremony pairs:

1. Registration (create)
2. Authentication (get)

Each pair has a server start step and a server finish step, with the platform authenticator in the middle.

sequenceDiagram
    autonumber
    actor User
    participant App as Client App
    participant Auth as Platform Authenticator
    participant RP as Relying Party Server

    note over RP,App: Registration ceremony
    App->>RP: registration/start request
    RP-->>App: registration/start response (challenge + options)
    App->>Auth: navigator.credentials.create / platform create
    Auth-->>App: RegistrationResponse
    App->>RP: registration/finish (response + echoed challenge)
    RP-->>App: verified registration

    note over RP,App: Authentication ceremony
    App->>RP: authentication/start request
    RP-->>App: authentication/start response (challenge + options)
    App->>Auth: navigator.credentials.get / platform get
    Auth-->>App: AuthenticationResponse
    App->>RP: authentication/finish (response + echoed challenge)
    RP-->>App: verified sign-in

Validation and trust decisions are server responsibilities: challenge/origin/type checks, authenticator data rules, signature/attestation verification, counter handling, and policy decisions.

The repository follows a layered model that keeps protocol and validation concerns separate from transport and platform adapters.

flowchart TB
    subgraph Layer1[Layer 1: Protocol Model]
        M[webauthn-model]
    end

    subgraph Layer2[Layer 2: Validation and Serialization]
        CBOR[webauthn-cbor-core]
        C[webauthn-core]
        S[webauthn-serialization-kotlinx]
        RUNTIME[webauthn-runtime-core]
    end

    subgraph Layer3[Layer 3: Crypto Abstractions and Backends]
        API[webauthn-crypto-api]
        JCRYPTO[webauthn-server-jvm-crypto]
    end

    subgraph Layer4[Layer 4: Server Services and Adapters]
        SVC[webauthn-server-core-jvm]
        KTOR[webauthn-server-ktor]
        STORE[webauthn-server-store-exposed]
        MDS[webauthn-attestation-mds]
    end

    subgraph Layer5[Layer 5: Client Orchestration and Platform]
        CCORE[webauthn-client-core]
        CJSON[webauthn-client-json-core]
        CANDROID[webauthn-client-android]
        CIOS[webauthn-client-ios]
        CCOMPOSE[webauthn-client-compose]
        CPRF[webauthn-client-prf-crypto]
        NET[webauthn-network-ktor-client]
    end

    M --> C
    M --> S
    CBOR --> S
    C --> API
    S --> SVC
    CBOR --> JCRYPTO
    JCRYPTO --> API
    C --> SVC
    SVC --> KTOR
    SVC --> STORE
    MDS --> API

    M --> CCORE
    RUNTIME --> CCORE
    RUNTIME --> CPRF
    RUNTIME --> NET
    CCORE --> CJSON
    CCORE --> CANDROID
    CCORE --> CIOS
    CCORE --> CCOMPOSE
    CCORE --> CPRF
    C --> NET
    S --> NET
    CCORE --> NET

Focus modules for this documentation round:

• core/ contains reusable protocol, validation, runtime, serialization, and crypto contracts.

• client/ contains shared client orchestration, platform bridges, Compose helpers, and client transport.

• server/ contains JVM server services, Ktor/store adapters, JVM crypto, and optional trust metadata.

• sample/ contains runnable samples and demo entry points; these modules are not published.

• webauthn-runtime-core: shared coroutine/failure boundary helpers for adapters.

• webauthn-model: typed protocol/value contracts.

• webauthn-core: standards-first ceremony validation.

• webauthn-client-core: shared passkey orchestration and controller flows.

• webauthn-client-compose: Compose integration helpers over client core.

• webauthn-client-prf-crypto: PRF-enabled key derivation/session crypto helpers.

Most module READMEs follow this baseline structure (adapted per module when needed):

• What it provides: the module's owned responsibilities.
• When to use: where it belongs in an integration.
• How to use: practical API snippets plus required caller responsibilities.
• How it fits in the system: dependency and data-flow context.
• Pitfalls/limits: common misuse patterns and intentional boundaries.
• Status: maturity and readiness signal.

Recommended adoption paths:

• Start server-side with model -> core -> crypto-api -> server-core-jvm (+ server-ktor if you want HTTP adapters).
• Start client-side with client-core -> platform bridge (+ client-compose for Compose UI).
• Add client-prf-crypto only when you need PRF-derived application crypto.

The coordinated release train uses one version for the full published surface plus a BOM.

repositories {
    google()
    mavenCentral()
}

Use only the modules your app actually wires in. In Kotlin Multiplatform projects, shared modules belong in commonMain, while concrete platform bridges belong in the matching platform source set.

Client-side KMP example:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(platform("io.github.szijpeter:webauthn-bom:<version>"))
            implementation("io.github.szijpeter:webauthn-client-core")
            implementation("io.github.szijpeter:webauthn-network-ktor-client") // optional default backend transport
        }

        androidMain.dependencies {
            implementation("io.github.szijpeter:webauthn-client-android") // only if you use AndroidPasskeyClient
        }

        iosMain.dependencies {
            implementation("io.github.szijpeter:webauthn-client-ios") // only if you use IosPasskeyClient
        }
    }
}

JVM/Ktor server example:

dependencies {
    implementation(platform("io.github.szijpeter:webauthn-bom:<version>"))
    implementation("io.github.szijpeter:webauthn-server-core-jvm")
    implementation("io.github.szijpeter:webauthn-server-jvm-crypto")
    implementation("io.github.szijpeter:webauthn-server-ktor") // optional route adapter
}

Notes:

• Client apps do not need webauthn-server-* dependencies.
• You only add webauthn-client-android / webauthn-client-ios when that target instantiates the concrete platform client.
• If you only use the shared client abstractions, commonMain only needs the common modules.
• For a complete source set example, see sample/compose-passkey, sample/compose-passkey-android, and sample/compose-passkey-ios.

Published to Maven Central (latest version is shown in the Maven Central badge above). Maintainers can still validate publication locally with:

./gradlew publishToMavenLocal --stacktrace

Use:

• webauthn-model
• webauthn-core
• webauthn-crypto-api
• webauthn-server-jvm-crypto
• webauthn-server-core-jvm
• webauthn-server-ktor if you want route adapters
• webauthn-server-store-exposed if you want an Exposed-backed store implementation

Use:

• webauthn-client-core
• webauthn-client-json-core if you exchange raw JSON with a host/backend
• webauthn-client-android
• webauthn-client-ios
• webauthn-client-compose for Compose helpers
• webauthn-client-prf-crypto for PRF-based key derivation and encryption helpers
• webauthn-network-ktor-client for the default backend contract (HttpClient-based API; add your preferred Ktor engine at app runtime)

Start with:

• sample/backend-ktor
• sample/compose-passkey
• sample/compose-passkey-ios
• sample/passkey-cli for a macOS-first experimental native-authenticator CLI POC

Desktop and CLI strategy notes for this repo live in docs/DESKTOP_CLI_STRATEGY.md.

This repository is publicly released and still pre-1.0.

Current state:

• Core/server validation paths are production-leaning.
• Publish/release infrastructure is now wired for Maven Central and compatibility baselines.
• Client flows are usable on Android and iOS with shared orchestration.
• iOS external security-key support is still being hardened before it can be documented as fully ready.
• kotlinx-serialization is now on 1.10.0 together with Signum 0.12.0 and indispensable 3.20.0; captured Android assertion-vector regressions are green on this combined dependency set.

• Vulnerability reporting: see SECURITY.md.
• Public-launch checklist: docs/PUBLIC_LAUNCH_CHECKLIST.md.
• Maven Central maintainer guide: docs/MAVEN_CENTRAL.md.
• Dependency automation is handled with Renovate.

tools/agent/setup-hooks.sh
tools/agent/quality-gate.sh --mode fast --scope changed --block false
tools/agent/quality-gate.sh --mode strict --scope changed --block false
./gradlew apiCheck --stacktrace
./gradlew publishToMavenLocal --stacktrace

• docs/wiki/README.md
• docs/CLIENT_FIRST_EXECUTION.md
• docs/CLIENT_API_BENCHMARKS.md
• docs/IMPLEMENTATION_STATUS.md
• docs/ROADMAP.md
• docs/ai/STEERING.md

License: Apache-2.0. See LICENSE.