Distribution & Registries¶

Every Surf Shield component ships to a predictable, publicly-documented artifact location. This page lists where each artifact lives, how to consume it, and where the matching releases are published.

Artifacts are published to the following locations:

leaf-ipc binaries (privileged sidecar) — as zip archives with a SHA-256 companion.
libleaf.* + leaf.h (C/C++ FFI) — as zip archives.
leafjni native JARs (Java JNI) — via Maven deployment.
leaf_sdk_desktop, leaf-build-deps, leaf-ipc crates — via cargo publish.

1. Repository URLs at a glance¶

Artifact kind	Public URL	Auth
Static zips (`leaf-ipc` core, FFI `libleaf.*`, checksums)	`https://repo.surfshield.org/repository/static-public/`	Anonymous read.
Java / Android (`leafjni`, `leaf-sdk-android`, `leaf-java-sdk`)	`https://repo.surfshield.org/repository/maven-public/`	Anonymous read.
Rust crates (`leaf_sdk_desktop`, `leaf-build-deps`, etc.)	`https://cargo.surfshield.org/` — Kellnr index `sparse+https://cargo.surfshield.org/api/v1/crates/`	Token required.

Both Nexus repositories (static-public, maven-public) are read-anonymous.

2. Rust crates (Kellnr)¶

Read destination: https://cargo.surfshield.org/.

Configure Cargo¶

Add a Kellnr registry to ~/.cargo/config.toml or a project-local .cargo/config.toml:

[registries.kellnr]
index = "sparse+https://cargo.surfshield.org/api/v1/crates/"
credential-provider = ["cargo:token"]

Provision a token¶

Open https://cargo.surfshield.org/ in a browser.
Sign in (ask [email protected] for credentials if you do not have them yet).
Navigate to My Account → Tokens and create a new token scoped to the crates you need.

Export it in your shell / CI, do not commit it:

export CARGO_REGISTRIES_KELLNR_TOKEN=<paste-here>

Depend on a private crate¶

[dependencies]
leaf_sdk_desktop = { version = "1.4.1", registry = "kellnr" }

[build-dependencies]
leaf-build-deps  = { version = "0.14.4", registry = "kellnr" }

The currently-published crates and their purposes:

Crate	Purpose	Docs
`leaf_sdk_desktop`	Rust SDK for desktop apps	Desktop SDK (Rust)
`leaf-ipc`	Privileged sidecar binary (can be built locally, or pulled via `leaf-build-deps`)	Architecture
`leaf-build-deps`	`build.rs` helper that downloads+verifies the right `leaf-ipc` for your target triple	below

3. `leaf-build-deps` — build.rs helper¶

If your Rust/Tauri app depends on leaf_sdk_desktop, you also have to ship leaf-ipc alongside the final executable. Instead of manually downloading matching binaries for each target, add leaf-build-deps as a build-dependency.

1. Add it to your `Cargo.toml`¶

[build-dependencies]
leaf-build-deps = { version = "0.14.4", registry = "kellnr" }

2. Use it in `build.rs`¶

use leaf_build_deps::LeafBuilder;

fn main() {
    LeafBuilder::new()
        // Optional overrides (defaults are reasonable):
        .cache_dir("./sidecar_cache") // where zips are cached between builds
        .output_dir("./bin")          // where the extracted binary lands
        .version("1.4.1")             // pin a known-good leaf-ipc version
        .build()
        .expect("failed to fetch leaf-ipc");

    tauri_build::build(); // or your own post-processing
}

On every cargo build the crate will:

Download leaf-ipc-core-<version>-<os>-<arch>.zip from https://repo.surfshield.org/repository/static-public/leaf-ipc-<version>/.
Verify the embedded .sha256 against the extracted binary.
Copy the binary to ./bin/leaf-ipc-<target-triple>[.exe].
Mark it executable on Unix.

3. Wire it into Tauri¶

// tauri.conf.json
{
  "bundle": {
    "externalBin": ["./bin/leaf-ipc"]
  }
}

Tauri then packages leaf-ipc as a sidecar, and your code starts it via app.shell().sidecar("leaf-ipc").

4. Supported target triples¶

leaf-build-deps maps Cargo's TARGET to these prebuilt bundles automatically:

`TARGET`	OS / arch bundle
`x86_64-unknown-linux-gnu`	`linux-64`
`i686-unknown-linux-gnu`	`linux-32`
`aarch64-unknown-linux-gnu`	`linux-arm64`
`armv7-unknown-linux-gnueabihf`	`linux-armv7`
`i686-pc-windows-msvc`	`windows-32`
`x86_64-pc-windows-msvc`	`windows-64`
`aarch64-pc-windows-msvc`	`windows-arm64`
`aarch64-apple-darwin`	`macos-arm64`
`x86_64-apple-darwin`	`macos-64`

4. Java / Android artifacts (Maven)¶

Public Maven URL: https://repo.surfshield.org/repository/maven-public/ (read-anonymous).

Add it to your Gradle setup:

Android (settings.gradle.kts)Java desktop (build.gradle)

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://repo.surfshield.org/repository/maven-public/") }
    }
}

repositories {
    mavenCentral()
    maven { url 'https://repo.surfshield.org/repository/maven-public/' }
}

Published modules:

Coordinates	Purpose	Docs
`com.github.shiroedev2024:leaf-sdk-android:<version>`	Android `VpnService` + JNI library	Android SDK
`com.github.shiroedev2024:leaf-java-sdk:<version>`	Desktop JVM SDK (JNI)	Desktop SDK (Java)
`com.github.shiroedev2024:leaf-jni-<target>-<version>`	Native JNI per-target JAR (transitively pulled)	—

If your artifact repository mirrors Maven Central, you only have to add maven-public as an extra repository; dependency resolution works as usual.

5. Static binaries (`leaf-ipc`, FFI)¶

Public URL: https://repo.surfshield.org/repository/static-public/.

Organised as follows:

static-public/
├── leaf-ipc-<version>/
│   └── leaf-ipc-core-<version>-<os>-<arch>.zip
│       └── bin/leaf-ipc[.exe]
│       └── bin/leaf-ipc[.exe].sha256
└── leaf-<ffi-version>/
    └── leaf-ffi-<ffi-version>-<os>-<arch>.zip
        ├── bin/leaf-ipc[.exe]
        ├── include/leaf.h
        └── lib/libleaf.{so,dylib,a} or leaf.{dll,lib}

Consume them manually when you cannot use leaf-build-deps (e.g. plain C/C++ apps):

curl -LO https://repo.surfshield.org/repository/static-public/leaf-2.4.0/leaf-ffi-2.4.0-linux-64.zip
unzip leaf-ffi-2.4.0-linux-64.zip
# contains include/leaf.h and lib/libleaf.so

Every binary is accompanied by a .sha256 sidecar — verify before use:

sha256sum -c bin/leaf-ipc.sha256

6. Sample projects (open source)¶

The sample clients that integrate the SDKs are open source under Apache 2.0:

github.com/shiroedev2024/leaf-android — Android reference client.
github.com/shiroedev2024/leaf-desktop — Tauri 2 + Vue 3 desktop client.

See Sample Projects for a feature-by-feature walk-through.

7. Licensing summary¶

Component	License
Leaf core (`leaf-ipc`, FFI `libleaf.*`, Android `libleaf.so`)	Closed source, licensed to paying customers. Binaries are redistributable as part of your app.
Surf Shield SDKs (`leaf_sdk_desktop`, `leaf-sdk-android`, `leaf-sdk-java`)	Apache 2.0 — binary distribution unrestricted.
`leaf-util`, `leaf-build-deps` helpers	Apache 2.0.
Sample apps (`leaf-android`, `leaf-desktop`)	Apache 2.0 — fork freely.

If you need a redistribution / OEM agreement for the core, email [email protected].

8. Version alignment cheat-sheet¶

Keep versions across the SDK boundary consistent:

Change	Must also update
Upgrade `leaf_sdk_desktop` in `Cargo.toml`	Bump the version you pass to `update_assets(major, minor, patch)` in your app.
Upgrade the `leaf-ipc` version in `LeafBuilder::version(...)`	Run `cargo clean` so the cached sidecar is re-fetched.
Upgrade `leaf-sdk-android` via Maven	Bump `BuildConfig.VERSION_NAME` so the Android sample's `updateAssets` call matches.
Upgrade `leaf-java-sdk` via Maven	No action needed — assets are keyed on the SDK version automatically.

See Architecture — Asset versioning rule for the full rationale.