setup

Initializes this TrustPin instance with the given configuration.

On Android — build configuration through a Context-aware entry point

On Android, always build configuration using one of these Context-aware factories:

• TrustPinConfiguration.fromAssets(context) — loads assets/trustpin.json.

• TrustPinConfiguration(...).withAndroidStorage(context) — programmatic.

Passing a configuration built without a Context on Android still works but weakens the instance's protection — always prefer the Context-aware factories above.

On JVM the Context-aware factories are unavailable and not needed; construct the configuration directly and pass it here.

Android: single-use contract for Context-decorated configurations

On Android, a configuration produced through one of the Context-aware factories above MUST be passed to exactly one setup call. Reusing the same decorated configuration silently downgrades subsequent instances. Build a fresh decorated configuration for each TrustPin instance — see withAndroidStorage for a worked example. This restriction does not apply on JVM.

What setup does — and does not — do

setup performs local validation only: it checks the credential shapes, stores them, and starts a background preload of the pinning configuration. It never waits for the network. Fetch and validation errors surface from awaitConfiguration — or, fail-closed, from verify at connection time.

Setup is one-shot: once an instance is configured, further setup calls throw TrustPinError.AlreadyInitialized. To use different credentials, create a new named instance via instance.

Recommended fail-closed integration pattern

If your app must not start networking without a validated pinning payload, gate on awaitConfiguration and treat any error as a hard stop:

try {
    // Android: use the Context-aware factory.
    TrustPin.setup(TrustPinConfiguration.fromAssets(context)) // local validation only
    TrustPin.awaitConfiguration(timeout = 10_000)             // fail-closed gate
} catch (e: TrustPinError) {
    // Hard stop. Do NOT fall through to an unpinned OkHttp client.
    return showRetryUi(e)
}
val client = OkHttpClient.Builder()
    .sslSocketFactory(TrustPin.makeSSLSocketFactory(), TrustPin.makeTrustManager())
    .build()

Apps that prefer zero launch latency can skip the gate — verify is fail-closed and refuses connections whenever the configuration cannot be fetched and validated.

Throws