Node.js SDK

The Node.js SDK reads secrets from your Burrow in a Node.js 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 Node.js 18.17 or later, has no runtime dependencies, and ships ESM, CommonJS and TypeScript types.

Install#

npm install @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.

import { Burrow } from "@ratelkey/burrow-sdk";

const burrow = Burrow();

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

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

To see what the machine can read:

for (const p of await burrow.listProjects()) console.log(`${p.project}: ${p.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.

const db = await burrow.live("payments/prod/DATABASE");

db.getField("password");                                // always the current value
db.on("change", (next, prev) => pool.reconnect(next));

liveEnvironment("payments/prod") does the same for a whole environment: env.get("API_KEY") reads one secret, and change lists 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, which reconnects on its own and picks up anything that changed while it was down. close() on the client closes them all.

Listen on status to follow it, and on error 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:

const burrow = Burrow.connect({
  burrowUrl: "https://burrow.internal:12010",
  machineId: "...",
  privateKeyPem: process.env.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.

const burrow = Burrow.enroll(process.env.BURROW_ENROLL_CODE!);

const apiKey = (await burrow.getSecret("payments/prod/API_KEY")).value;

// On shutdown
await burrow.close();

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:

const burrow = Burrow.oidc({
  burrowUrl: "https://burrow.example.com",
  fingerprint: process.env.BURROW_FINGERPRINT, // leave out for a publicly-trusted certificate
});

const apiKey = (await 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:

import { Burrow, TlsMode } from "@ratelkey/burrow-sdk";

const burrow = Burrow(null, { tls: TlsMode.SystemTrust });

Verify webhooks#

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

import express from "express";
import { verifyWebhook } from "@ratelkey/burrow-sdk";

const app = express();
app.post("/hooks/burrow", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyWebhook(req.body, req.headers, process.env.BURROW_WEBHOOK_SECRET!);
  console.log(event.event, event.data.summary);
  res.sendStatus(204);
});

Pass the raw request body, before any JSON parsing. The headers can be Node's headers object or a Fetch 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.