Installation

This guide covers repository configuration, the module architecture, and dependency setup for the IDK.

Repository Configuration

IDK artifacts are published to the Sphereon Maven repository.

Kotlin (Gradle)

Add the repository to your settings.gradle.kts or root build.gradle.kts:

repositories {
    mavenCentral()
    maven {
        url = uri("https://nexus.sphereon.com/repository/sphereon-opensource-releases/")
    }
    maven {
        url = uri("https://nexus.sphereon.com/repository/sphereon-opensource-snapshots/")
    }
}

iOS (Swift)

Add the IDK Swift package to your Xcode project:

1. Open your project in Xcode
2. Select File > Add Package Dependencies
3. Enter the package URL: https://github.com/nicklasw/idk-swift
4. Select the version or branch you want to use

Or add the package to your Package.swift:

dependencies: [
    .package(url: "https://github.com/nicklasw/idk-swift", from: "0.25.0")
]

JavaScript / WASM

For JavaScript and WebAssembly targets, IDK modules are published as npm packages. Add the Sphereon registry to your .npmrc:

@sphereon:registry=https://nexus.sphereon.com/repository/sphereon-opensource-npm/

Then install modules as needed:

npm install @sphereon/idk-crypto-core @sphereon/idk-sdjwt

Module Architecture

The IDK follows a strict separation between public API and implementation modules. Understanding this is important for building maintainable applications.

The -public / -impl Pattern

Most IDK domains ship as a pair of modules:

Module	Contains	Depend on it when...
lib-<domain>-public	Interfaces, data classes, sealed types, commands, low-level common logic	You are writing library code, services, or any code that should not be tied to a specific implementation
lib-<domain>-impl	Injectable implementations, DI contributions (@ContributesBinding, @ContributesIntoSet), concrete service classes	You are assembling the final application that needs actual running code

The exception is lib-core-api, where the implementation module is called lib-core-api-default instead of -impl.

In Practice

Your own code should only depend on -public modules. This way it stays decoupled from implementation details and works with any backing implementation: the standard one, a test double, or a custom override you write.

The -impl modules belong at the application assembly level, the Gradle module that defines your @DependencyGraph and produces the final binary. That's where Metro wires all the @ContributesBinding and @ContributesIntoSet contributions into the dependency graph.

your-library/
  build.gradle.kts → depends on lib-crypto-core-public, lib-sdjwt-public
  src/ → uses IIdentifierService, SdJwtService interfaces

your-app/
  build.gradle.kts → depends on your-library + all -impl modules
  src/ → defines @DependencyGraph, brings everything together

This pattern is enforced by the DI system: -public modules declare the interfaces and bindings; -impl modules contribute the concrete implementations. If you forget to include an -impl module in your final application, Metro will report a missing binding at compile time.

All-in-One Dependency

For getting started quickly, or for applications that use most IDK features, include the lib-all artifact:

Kotlin (Gradle)

dependencies {
    implementation("com.sphereon.idk:lib-all:0.25.0")
}

iOS (Swift)

// The iOS XCFramework package includes all modules
import SphereonIDK

This pulls in every IDK module. For production applications where binary size or dependency footprint matters, switch to individual modules (see the Module Reference for the full list).

Metro Compiler Plugin

The IDK uses Metro for dependency injection. Apply the Metro Gradle plugin to every module that defines a @DependencyGraph or uses Metro annotations:

build.gradle.kts

plugins {
    id("dev.zacsweers.metro") version "<version>"
}

Metro is a Kotlin compiler plugin, so no KSP or annotation processing step is needed. See Extending the DI Graph for details on Metro annotations and contributing custom services.

Selective Dependencies

When you need fine-grained control over what's included, add modules individually. Here's a minimal example for an SD-JWT verifier application:

build.gradle.kts

dependencies {
    // Core (always needed)
    implementation("com.sphereon.idk:lib-core-api-public:0.25.0")
    implementation("com.sphereon.idk:lib-core-api-default:0.25.0")

    // Crypto for signature verification
    implementation("com.sphereon.idk:lib-crypto-core-public:0.25.0")
    implementation("com.sphereon.idk:lib-crypto-core-impl:0.25.0")
    implementation("com.sphereon.idk:lib-crypto-kms-provider-software:0.25.0")

    // SD-JWT
    implementation("com.sphereon.idk:lib-sdjwt-public:0.25.0")
    implementation("com.sphereon.idk:lib-sdjwt-impl:0.25.0")

    // DID resolution (for resolving issuer keys)
    implementation("com.sphereon.idk:lib-did-core-public:0.25.0")
    implementation("com.sphereon.idk:lib-did-resolver-public:0.25.0")
    implementation("com.sphereon.idk:lib-did-resolver-impl:0.25.0")
    implementation("com.sphereon.idk:lib-did-methods-key:0.25.0")
    implementation("com.sphereon.idk:lib-did-methods-web:0.25.0")

    // Trust validation
    implementation("com.sphereon.idk:lib-trust-core-public:0.25.0")
    implementation("com.sphereon.idk:lib-trust-core-impl:0.25.0")

    // Key-value store (required by core)
    implementation("com.sphereon.idk:lib-data-store-kv-public:0.25.0")
    implementation("com.sphereon.idk:lib-data-store-kv-impl:0.25.0")
    implementation("com.sphereon.idk:lib-data-store-kv-impl-memory:0.25.0")
}

See the Module Reference for the complete catalog of available modules organized by domain.

Bill of Materials (BOM)

To align all IDK module versions without specifying each one, use the BOM:

build.gradle.kts

dependencies {
    implementation(platform("com.sphereon.idk:idk-bom:0.25.0"))

    // Now you can omit versions
    implementation("com.sphereon.idk:lib-crypto-core-public")
    implementation("com.sphereon.idk:lib-crypto-core-impl")
    implementation("com.sphereon.idk:lib-sdjwt-public")
    implementation("com.sphereon.idk:lib-sdjwt-impl")
}

Next Steps

• Module Reference: full list of all available modules with descriptions
• Platform Setup: Android, iOS, and platform-specific configuration
• Dependency Injection: understanding scopes and setting up your application graph