.NET SDK

The .NET SDK reads secrets from your Burrow in a .NET 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 .NET 8 or later.

Install#

dotnet add package RatelKey.Burrow.Sdk

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.

using RatelKey.Burrow;

using var burrow = Burrow.Open();

// A single-value secret
var apiKey = (await burrow.GetSecretAsync("payments/prod/API_KEY")).Value;

// A structured secret
var db = await burrow.GetSecretAsync("payments/prod/DATABASE");
var all = db.ToDictionary();                            // every field, name to value
var host = db.GetField("host");                         // one field
var fields = db.GetFields("username", "password");      // several, in order

To see what the machine can read:

foreach (var p in await burrow.ListProjectsAsync())
    Console.WriteLine($"{p.Project}: {string.Join(", ", p.Categories)}");

ListSecretsAsync 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 handle Changed to act on changes.

var db = await burrow.LiveAsync("payments/prod/DATABASE");

db.GetField("password");                                 // always the current value
db.Changed += (_, change) => pool.Reconnect(change.Next);

LiveEnvironmentAsync("payments/prod") does the same for a whole environment: env.Get("API_KEY") reads one secret, and Changed lists what changed, was added or was removed.

The call completes after the first read, so a missing secret or grant fails there. All live secrets on a client share one connection, which reconnects on its own and picks up anything that changed while it was down. Events are raised on the SDK's threads. Closing or disposing the client closes them all.

Handle StatusChanged to follow it, and Error for a handler that threw or a read that failed.

Choose an identity#

With one machine identity on the host, Burrow.Open() 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.Open("burrow-a1b2c3d4e5f60718");
Burrow.Open("/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:

using var burrow = Burrow.Connect(
    burrowUrl: "https://burrow.internal:12010",
    machineId: "...",
    privateKeyPem: Environment.GetEnvironmentVariable("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.

await using var burrow = Burrow.Enroll(Environment.GetEnvironmentVariable("BURROW_ENROLL_CODE")!);

var apiKey = (await burrow.GetSecretAsync("payments/prod/API_KEY")).Value;

Before the machine expires, the SDK enrolls a fresh one with the same code. CloseAsync(), or disposing the client, ends the machine at once, so it shows as Expired on the Burrow. With no identity under ~/.burrow, Burrow.Open() 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:

using var burrow = Burrow.Oidc(
    burrowUrl: "https://burrow.example.com",
    fingerprint: Environment.GetEnvironmentVariable("BURROW_FINGERPRINT")); // leave out for a publicly-trusted certificate

var apiKey = (await burrow.GetSecretAsync("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:

using var burrow = Burrow.Open(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 an ASP.NET Core minimal API:

app.MapPost("/hooks/burrow", async (HttpRequest request) =>
{
    using var body = new MemoryStream();
    await request.Body.CopyToAsync(body);
    var e = BurrowWebhooks.Verify(body.ToArray(), request.Headers[BurrowWebhooks.SignatureHeader],
        Environment.GetEnvironmentVariable("BURROW_WEBHOOK_SECRET")!);
    Console.WriteLine($"{e.Event} {e.Data.Summary}");
    return Results.NoContent();
});

Pass the raw request body, before any JSON parsing. A retried delivery carries the same 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.