Kotlin SDK

The Kotlin SDK reads secrets from your Burrow in a Kotlin or other JVM application, signed in as a machine you enrolled. It reads single-value and structured secrets, keeps them current as they change, lists what the machine has access to, and verifies your Burrow's signed webhooks. It needs JDK 17 or later.

Install#

Add the SDK from Maven Central. With Gradle:

dependencies {
    implementation("com.ratelkey:burrow-sdk:1.1.0")
}

Enroll the machine#

The SDK reads as a machine. Enroll the host your application runs on as described in Command / Ed25519. The command stores the machine's identity under ~/.burrow on that host, where the SDK finds it. Then give the machine the projects and environments it reads from Machine grants.

Read a secret#

A secret is addressed as project/environment/NAME. A structured secret comes back in one request, and its fields are read from the result without asking the Burrow again.

import com.ratelkey.burrow.Burrow

val burrow = Burrow()

// A single-value secret
val apiKey = burrow.getSecret("payments/prod/API_KEY").value

// A structured secret
val db = burrow.getSecret("payments/prod/DATABASE")
val all = db.toMap()                                     // every field, name to value
val host = db.getField("host")                           // one field
val (user, pass) = db.getFields("username", "password")  // several, in order

To see what the machine can read:

burrow.listProjects().forEach { println("${it.project}: ${it.categories}") }

listSecrets lists the secrets in an environment the machine can read.

Live secrets#

A live secret holds the secret's current value and follows every change on the Burrow as it is saved. Read it whenever you need the value, and listen for changes to act on them.

val db = burrow.live("payments/prod/DATABASE")

db.getField("password")                                  // always the current value
db.onChange { next, prev -> pool.reconnect(next) }

liveEnvironment("payments/prod") does the same for a whole environment: env["API_KEY"] reads one secret, and onChange receives what changed, was added or was removed.

The call returns after the first read, so a missing secret or grant fails there. All live secrets on a client share one connection on a background thread, which reconnects on its own and picks up anything that changed while it was down. Listeners run on the SDK's threads, and closing what onChange returns removes the listener. close() on the client closes them all.

Use onStatus to follow it, and onError for a listener that threw or a read that failed.

Choose an identity#

With one machine identity on the host, Burrow() uses it. With several, name the one to use by its Burrow's slug or name, the machine id, or the Burrow's URL, or give the path to its folder or its identity.json. To keep identities somewhere other than ~/.burrow, set BURROW_HOME.

Burrow("burrow-a1b2c3d4e5f60718")
Burrow("/home/you/.burrow/burrows/burrow-a1b2c3d4e5f60718")

Supply the key yourself#

An application that keeps its own key material can pass the Burrow's address, the machine id and the machine's private key, as PKCS#8 PEM, directly:

val burrow = Burrow.connect(
    burrowUrl = "https://burrow.internal:12010",
    machineId = "...",
    privateKeyPem = System.getenv("BURROW_MACHINE_KEY"),
)

Enroll in memory#

To keep nothing on disk, as in a container, enroll with the code of a machine token. The SDK generates the machine's key in memory and enrolls on the first read. The code carries the Burrow's address and how to trust its certificate.

Burrow.enroll(System.getenv("BURROW_ENROLL_CODE")).use { burrow ->
    val apiKey = burrow.getSecret("payments/prod/API_KEY").value
}

Before the machine expires, the SDK enrolls a fresh one with the same code. close() ends the machine at once, so it shows as Expired on the Burrow. With no identity under ~/.burrow, Burrow() enrolls from BURROW_ENROLL_CODE.

OIDC#

In a CI job such as GitHub Actions, the SDK can authenticate with the token the CI provider mints for each run, with no key on the runner. Register the machine for the workflow first, then:

val burrow = Burrow.oidc(
    burrowUrl = "https://burrow.example.com",
    fingerprint = System.getenv("BURROW_FINGERPRINT"), // leave out for a publicly-trusted certificate
)

val apiKey = burrow.getSecret("payments/prod/API_KEY").value

The audience defaults to the Burrow's address. If you registered the machine with a different one, pass it as audience.

Certificate trust#

By default the SDK trusts the Burrow the way you chose under Connection when the machine was added. To override it, pass tls:

val burrow = Burrow(tls = TlsMode.SystemTrust)

Verify webhooks#

For a Signed webhook, BurrowWebhooks.verify checks that a delivery came from your Burrow and returns the event. It needs only the webhook's signing secret, with no machine identity. In a Ktor route:

post("/hooks/burrow") {
    val event = BurrowWebhooks.verify(
        call.receive<ByteArray>(),
        call.request.headers[BurrowWebhooks.SIGNATURE_HEADER],
        System.getenv("BURROW_WEBHOOK_SECRET"),
    )
    println("${event.event} ${event.data.summary}")
    call.respond(HttpStatusCode.NoContent)
}

Pass the raw request body, before any JSON parsing. verify also takes a map of headers. A retried delivery carries the same event.id, so keep the ids you've handled and skip repeats.

Errors#

Every failure throws a BurrowException, and its message carries the Burrow's own reason.