@ratelkey/burrow-sdk 0.1.0

package/dist/cjs/Model.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectAccess = exports.SecretCoordinate = exports.Secret = void 0;
+const Errors_js_1 = require("./Errors.js");
+/**
+ * A secret read from a Burrow — fetched whole in a single signed call. Project it locally (no re-fetch):
+ *
+ * ```ts
+ * const db = await burrow.getSecret("payments/prod/DATABASE");
+ * db.value;                                        // a single-value secret
+ * db.toMap();                                      // every field as name → value
+ * db.getField("password");                         // one field
+ * const [user, pass] = db.getFields("username", "password");  // in order — destructures
+ * ```
+ *
+ * A shape mismatch (e.g. `value` on a structured secret, or `toMap()` on a single one) throws
+ * {@link SecretShapeException}; a missing field throws {@link FieldNotFoundException}.
+ */
+class Secret {
+    name;
+    singleValue;
+    singleType;
+    singleVersion;
+    fieldsByName;
+    constructor(
+    /** The secret's name (the final segment of its `project/env/NAME` coordinate). */
+    name, singleValue, singleType, singleVersion, fieldsByName) {
+        this.name = name;
+        this.singleValue = singleValue;
+        this.singleType = singleType;
+        this.singleVersion = singleVersion;
+        this.fieldsByName = fieldsByName;
+    }
+    /** True when this is a structured (multi-field) secret rather than a single value. */
+    get isStructured() {
+        return this.fieldsByName !== null;
+    }
+    /** The single value. Throws {@link SecretShapeException} if this is a structured secret. */
+    get value() {
+        if (this.singleValue === null) {
+            throw new Errors_js_1.SecretShapeException(`'${this.name}' is a structured secret; use toMap(), getField(), or getFields()`);
+        }
+        return this.singleValue;
+    }
+    /** The declared type of a single-value secret; null for a structured one. */
+    get type() {
+        return this.singleType;
+    }
+    /** The current version of a single-value secret; null for a structured one. */
+    get version() {
+        return this.singleVersion;
+    }
+    /** Every field as a name → value map. Throws {@link SecretShapeException} if this is a single-value secret. */
+    toMap() {
+        const out = {};
+        for (const [name, field] of this.structured())
+            out[name] = field.value;
+        return out;
+    }
+    /** The typed fields. Throws {@link SecretShapeException} if this is a single-value secret. */
+    fields() {
+        return [...this.structured().values()];
+    }
+    /**
+     * One field's value. Throws {@link SecretShapeException} if single-value, or
+     * {@link FieldNotFoundException} if absent.
+     */
+    getField(field) {
+        const f = this.structured();
+        const hit = f.get(field);
+        if (hit === undefined)
+            throw new Errors_js_1.FieldNotFoundException(this.name, field, f.keys());
+        return hit.value;
+    }
+    /**
+     * The named fields' values, in the order given — for destructuring:
+     * `const [user, pass] = secret.getFields("username", "password")`. Throws {@link SecretShapeException} if
+     * single-value, or {@link FieldNotFoundException} if any name is absent.
+     */
+    getFields(...names) {
+        const f = this.structured();
+        return names.map((n) => {
+            const hit = f.get(n);
+            if (hit === undefined)
+                throw new Errors_js_1.FieldNotFoundException(this.name, n, f.keys());
+            return hit.value;
+        });
+    }
+    structured() {
+        if (this.fieldsByName === null) {
+            throw new Errors_js_1.SecretShapeException(`'${this.name}' is a single-value secret; use value`);
+        }
+        return this.fieldsByName;
+    }
+    /** @internal */
+    static single(name, value, type, version) {
+        return new Secret(name, value, type, version, null);
+    }
+    /** @internal */
+    static structured(name, fields) {
+        return new Secret(name, null, null, null, fields);
+    }
+}
+exports.Secret = Secret;
+/** A secret this machine can read, addressed by its `project / env / name` coordinate. */
+class SecretCoordinate {
+    project;
+    environment;
+    name;
+    constructor(project, environment, name) {
+        this.project = project;
+        this.environment = environment;
+        this.name = name;
+    }
+    /** The `project/env/NAME` slug form, as the Burrow lists it and `BurrowClient.getSecret` takes it. */
+    toString() {
+        return `${this.project}/${this.environment}/${this.name}`;
+    }
+    /** Parse a `project/env/NAME` slug into its parts. */
+    static parse(slug) {
+        // Split into at most three parts: a secret name may legitimately contain a slash, the coordinate's
+        // first two separators may not.
+        const first = slug.indexOf("/");
+        if (first < 0)
+            return new SecretCoordinate(slug, "", "");
+        const second = slug.indexOf("/", first + 1);
+        if (second < 0)
+            return new SecretCoordinate(slug.slice(0, first), slug.slice(first + 1), "");
+        return new SecretCoordinate(slug.slice(0, first), slug.slice(first + 1, second), slug.slice(second + 1));
+    }
+}
+exports.SecretCoordinate = SecretCoordinate;
+/** A project this machine can read, and the environment categories it holds a grant for. */
+class ProjectAccess {
+    project;
+    categories;
+    constructor(project, categories) {
+        this.project = project;
+        this.categories = categories;
+    }
+}
+exports.ProjectAccess = ProjectAccess;
+//# sourceMappingURL=Model.js.map

package/dist/cjs/Model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Model.js","sourceRoot":"","sources":["../../src/Model.ts"],"names":[],"mappings":"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"}

package/dist/cjs/Signer.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MachineSigner = void 0;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Builds the Ed25519-signed `Ratel-*` headers for a machine-plane request. The canonical string MUST
+ * byte-match the Burrow's `MachineSignature.canonical`, or every read is rejected 401:
+ *
+ * ```
+ * ACTION \n resource[0] \n … \n resource[n] \n TIMESTAMP \n NONCE \n CLIENT      (no trailing newline)
+ * ```
+ *
+ * TIMESTAMP is unix millis as a decimal string; the SAME string goes in the header and the signed bytes. A
+ * fresh timestamp + nonce per call makes a captured request unreplayable (the Burrow enforces a tight
+ * timestamp window and a single-use nonce).
+ */
+exports.MachineSigner = {
+    canonical(action, resource, timestamp, nonce, client) {
+        let out = `${action}\n`;
+        for (const part of resource)
+            out += `${part}\n`;
+        out += `${timestamp}\n${nonce}\n${client}`;
+        return Buffer.from(out, "utf8");
+    },
+    /** The signed `Ratel-*` headers for one request. */
+    sign(machineId, key, action, resource, client, nowMillis) {
+        const timestamp = String(nowMillis);
+        // Standard base64 with padding — the Burrow decodes with java.util.Base64's standard decoder. 16 bytes
+        // encodes to 24 characters, well inside the Burrow's 64-character nonce bound.
+        const nonce = (0, node_crypto_1.randomBytes)(16).toString("base64");
+        // Ed25519 signs the message directly: the digest algorithm must be null, not a hash name.
+        const signature = (0, node_crypto_1.sign)(null, exports.MachineSigner.canonical(action, resource, timestamp, nonce, client), key).toString("base64");
+        return {
+            "Ratel-Machine": machineId,
+            "Ratel-Timestamp": timestamp,
+            "Ratel-Nonce": nonce,
+            "Ratel-Signature": signature,
+            "Ratel-Client": client,
+        };
+    },
+};
+//# sourceMappingURL=Signer.js.map

package/dist/cjs/Signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Signer.js","sourceRoot":"","sources":["../../src/Signer.ts"],"names":[],"mappings":";;;AAAA,6CAA6E;AAE7E;;;;;;;;;;;GAWG;AACU,QAAA,aAAa,GAAG;IAC3B,SAAS,CACP,MAAc,EACd,QAA2B,EAC3B,SAAiB,EACjB,KAAa,EACb,MAAc;QAEd,IAAI,GAAG,GAAG,GAAG,MAAM,IAAI,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,QAAQ;YAAE,GAAG,IAAI,GAAG,IAAI,IAAI,CAAC;QAChD,GAAG,IAAI,GAAG,SAAS,KAAK,KAAK,KAAK,MAAM,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,oDAAoD;IACpD,IAAI,CACF,SAAiB,EACjB,GAAc,EACd,MAAc,EACd,QAA2B,EAC3B,MAAc,EACd,SAAiB;QAEjB,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QACpC,uGAAuG;QACvG,+EAA+E;QAC/E,MAAM,KAAK,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjD,0FAA0F;QAC1F,MAAM,SAAS,GAAG,IAAA,kBAAS,EACzB,IAAI,EACJ,qBAAa,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,EACnE,GAAG,CACJ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACrB,OAAO;YACL,eAAe,EAAE,SAAS;YAC1B,iBAAiB,EAAE,SAAS;YAC5B,aAAa,EAAE,KAAK;YACpB,iBAAiB,EAAE,SAAS;YAC5B,cAAc,EAAE,MAAM;SACvB,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/cjs/Tls.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PinStore = exports.TlsMode = void 0;
+exports.publicKeyPin = publicKeyPin;
+exports.fingerprintsEqual = fingerprintsEqual;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** The three trust modes, as values: `TlsMode.Pinned`, `TlsMode.PinnedTo("aa:bb:…")`, `TlsMode.SystemTrust`. */
+exports.TlsMode = {
+    Pinned: { kind: "pinned" },
+    PinnedTo: (fingerprint) => ({ kind: "pinnedTo", fingerprint }),
+    SystemTrust: { kind: "systemTrust" },
+};
+/**
+ * SHA-256 of a certificate's PUBLIC KEY (its SubjectPublicKeyInfo) as lowercase colon-separated hex — the
+ * form the Burrow shows in Settings → Network and carries in a bootstrap code.
+ *
+ * The key rather than the whole certificate. A Burrow's certificate legitimately changes — a custom domain
+ * added to its SANs, an ACME renewal, a refresh — while the Burrow itself is the same one. Pinning the
+ * certificate turned each of those into "this is a different server", and a machine that had done nothing
+ * wrong stopped being able to read secrets.
+ *
+ * Parsed through `X509Certificate` and exported as SPKI DER rather than read off `getPeerCertificate().pubkey`,
+ * because that field's encoding is not documented to be SPKI and a pin has to hash exactly what the Burrow
+ * hashed.
+ */
+function publicKeyPin(der) {
+    const spki = new node_crypto_1.X509Certificate(Buffer.from(der)).publicKey.export({ type: "spki", format: "der" });
+    const hex = (0, node_crypto_1.createHash)("sha256").update(spki).digest("hex");
+    return (hex.match(/../g) ?? []).join(":");
+}
+/** Compare two fingerprints ignoring case and separators, so "AA:BB…" and "aabb…" match. */
+function fingerprintsEqual(a, b) {
+    const norm = (s) => s.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+    const na = norm(a);
+    return na.length > 0 && na === norm(b);
+}
+/**
+ * One Burrow's pinned key, at `<identity dir>/known_cert`, shared with the `ratel` CLI.
+ *
+ * Per burrow rather than one map for the machine. The pin and the identity are the same trust relationship:
+ * removing a Burrow should forget it entirely, and a shared file left the pin behind for a Burrow that no
+ * longer had an identity. It also means two Burrows can never contend for one file.
+ *
+ * A single value, not a map keyed by URL: the pin is the Burrow's KEY, so the same Burrow reached by its LAN
+ * address, its public address or its relay hostname presents the same one.
+ *
+ * Reads tolerate a missing or unreadable file (treated as unpinned); writes are atomic (temp file + rename)
+ * so concurrent SDK/CLI processes can't tear it. A null directory keeps the pin in memory only.
+ */
+class PinStore {
+    file;
+    constructor(dir) {
+        this.file = dir === null ? null : (0, node_path_1.join)(dir, "known_cert");
+    }
+    read() {
+        if (this.file === null)
+            return null;
+        try {
+            return (0, node_fs_1.readFileSync)(this.file, "utf8").trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    write(pin) {
+        if (this.file === null)
+            return;
+        if (this.read() === pin)
+            return;
+        // Best-effort: a read-only home just means the next process re-pins. Never fail a read over it.
+        try {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.file), { recursive: true });
+            const tmp = `${this.file}.tmp`;
+            (0, node_fs_1.writeFileSync)(tmp, `${pin}\n`);
+            (0, node_fs_1.renameSync)(tmp, this.file);
+        }
+        catch {
+            // ignored
+        }
+    }
+}
+exports.PinStore = PinStore;
+//# sourceMappingURL=Tls.js.map

package/dist/cjs/Tls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tls.js","sourceRoot":"","sources":["../../src/Tls.ts"],"names":[],"mappings":";;;AA+CA,oCAIC;AAGD,8CAIC;AA1DD,6CAA0D;AAC1D,qCAA6E;AAC7E,yCAA0C;AAyB1C,gHAAgH;AACnG,QAAA,OAAO,GAAG;IACrB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAa;IACrC,QAAQ,EAAE,CAAC,WAAmB,EAAW,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;IAC/E,WAAW,EAAE,EAAE,IAAI,EAAE,aAAa,EAAa;CACvC,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,SAAgB,YAAY,CAAC,GAAe;IAC1C,MAAM,IAAI,GAAG,IAAI,6BAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACrG,MAAM,GAAG,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED,4FAA4F;AAC5F,SAAgB,iBAAiB,CAAC,CAAS,EAAE,CAAS;IACpD,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACjF,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAa,QAAQ;IACF,IAAI,CAAgB;IAErC,YAAY,GAAkB;QAC5B,IAAI,CAAC,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC5D,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,IAAA,sBAAY,EAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAW;QACf,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO;QAC/B,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG;YAAE,OAAO;QAChC,gGAAgG;QAChG,IAAI,CAAC;YACH,IAAA,mBAAS,EAAC,IAAA,mBAAO,EAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,MAAM,CAAC;YAC/B,IAAA,uBAAa,EAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,CAAC;YAC/B,IAAA,oBAAU,EAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,UAAU;QACZ,CAAC;IACH,CAAC;CACF;AA7BD,4BA6BC"}

package/dist/cjs/Transport.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = void 0;
+const node_http_1 = require("node:http");
+const node_net_1 = require("node:net");
+const node_tls_1 = require("node:tls");
+const Errors_js_1 = require("./Errors.js");
+const Tls_js_1 = require("./Tls.js");
+const TIMEOUT_MS = 15_000;
+/**
+ * Performs signed machine-plane GETs against one Burrow, applying the configured {@link TlsMode}. Burrows
+ * serve HTTPS self-signed by default, so `TlsMode.Pinned` pins the certificate trust-on-first-use and
+ * refuses a changed one. Maps the Burrow's HTTP status + `{"error": …}` body to the typed
+ * {@link BurrowException}s, and surfaces the Burrow's own rejection reason verbatim.
+ *
+ * The TLS handshake is completed and the pin checked BEFORE the HTTP request is handed the socket, so a
+ * mismatched certificate never sees the signed `Ratel-*` headers. That ordering is the whole point of
+ * pinning, and it is why this dials the socket itself rather than letting the HTTP agent do it.
+ */
+class Transport {
+    tls;
+    base;
+    pins;
+    /** The fingerprint currently enforced. Null in trust-on-first-use mode until the first pin is learned. */
+    pinned;
+    constructor(burrowUrl, tls, 
+    /** This Burrow's identity directory — where its pinned key lives, beside the key that signs for it. */
+    identityDir) {
+        this.tls = tls;
+        this.base = burrowUrl.replace(/\/+$/, "");
+        this.pins = new Tls_js_1.PinStore(identityDir);
+        this.pinned = tls.kind === "pinnedTo" ? tls.fingerprint : tls.kind === "pinned" ? this.pins.read() : null;
+    }
+    /** Signed GET, returning the response body on 2xx; throws a typed {@link BurrowException} otherwise. */
+    async get(path, headers) {
+        const url = this.resolve(path);
+        const conn = await this.connect(url);
+        let status;
+        let body;
+        try {
+            ({ status, body } = await exchange(conn.socket, url, headers));
+        }
+        catch (e) {
+            throw new Errors_js_1.BurrowTransportException(`reaching burrow ${this.base}: ${messageOf(e)}`, { cause: e });
+        }
+        finally {
+            conn.socket.destroy();
+        }
+        if (status < 200 || status > 299)
+            throw this.errorFor(status, body);
+        this.commitPinIfNew(conn.fingerprint);
+        return body;
+    }
+    resolve(path) {
+        let url;
+        try {
+            url = new URL(this.base + path);
+        }
+        catch (e) {
+            throw new Errors_js_1.BurrowTransportException(`invalid burrow URL '${this.base}${path}': ${messageOf(e)}`, { cause: e });
+        }
+        if (url.protocol !== "https:" && url.protocol !== "http:") {
+            throw new Errors_js_1.BurrowTransportException(`burrow URL '${this.base}' is not http(s)`);
+        }
+        return url;
+    }
+    /** Dial the Burrow and, for the pinned modes, verify its certificate before anything is written. */
+    connect(url) {
+        const host = url.hostname;
+        const port = url.port.length > 0 ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+        // Pinning is authoritative for a self-signed Burrow, so the CA chain and hostname checks are waived —
+        // the certificate is reached by IP or a self-signed domain that no SAN or CA would match. SystemTrust
+        // keeps the full standard verification and needs no pin check of its own.
+        const pinning = this.tls.kind !== "systemTrust";
+        const socket = url.protocol === "http:"
+            ? (0, node_net_1.connect)({ host, port })
+            : (0, node_tls_1.connect)({
+                host,
+                port,
+                // SNI carries a hostname; an IP literal is not a legal server name.
+                ...((0, node_net_1.isIP)(host) === 0 ? { servername: host } : {}),
+                rejectUnauthorized: !pinning,
+            });
+        return new Promise((resolve, reject) => {
+            const finish = (settle) => {
+                socket.removeListener("error", onError);
+                socket.removeListener("timeout", onTimeout);
+                socket.removeListener("secureConnect", onSecure);
+                socket.removeListener("connect", onPlain);
+                socket.setTimeout(0);
+                // Hold a no-op error listener so a fault between here and the HTTP client taking the socket over is
+                // never an unhandled 'error' event, which would take the process down.
+                socket.on("error", ignore);
+                settle();
+            };
+            const onError = (e) => finish(() => reject(new Errors_js_1.BurrowTransportException(`reaching burrow ${this.base}: ${e.message}`, { cause: e })));
+            const onTimeout = () => {
+                socket.destroy();
+                finish(() => reject(new Errors_js_1.BurrowTransportException(`reaching burrow ${this.base}: timed out after ${TIMEOUT_MS}ms`)));
+            };
+            const onPlain = () => finish(() => resolve({ socket, fingerprint: null }));
+            const onSecure = () => {
+                if (!pinning) {
+                    finish(() => resolve({ socket, fingerprint: null }));
+                    return;
+                }
+                const der = socket.getPeerCertificate().raw;
+                if (der === undefined || der.length === 0) {
+                    socket.destroy();
+                    finish(() => reject(new Errors_js_1.BurrowCertificateException("Burrow presented no certificate")));
+                    return;
+                }
+                const seen = (0, Tls_js_1.publicKeyPin)(der);
+                const pin = this.pinned;
+                if (pin !== null && !(0, Tls_js_1.fingerprintsEqual)(seen, pin)) {
+                    socket.destroy();
+                    finish(() => reject(new Errors_js_1.BurrowCertificateException(`Burrow key does not match the pinned one (pinned=${pin}, got=${seen})`)));
+                    return;
+                }
+                finish(() => resolve({ socket, fingerprint: seen }));
+            };
+            socket.setTimeout(TIMEOUT_MS);
+            socket.once("timeout", onTimeout);
+            socket.once("error", onError);
+            if (url.protocol === "https:")
+                socket.once("secureConnect", onSecure);
+            else
+                socket.once("connect", onPlain);
+        });
+    }
+    commitPinIfNew(fingerprint) {
+        if (fingerprint === null)
+            return;
+        if (this.tls.kind !== "pinned")
+            return; // only TOFU persists; PinnedTo is caller-fixed, never learned
+        if (this.pinned !== null)
+            return;
+        this.pins.write(fingerprint);
+        this.pinned = fingerprint; // enforce on subsequent requests within this process too
+    }
+    errorFor(status, body) {
+        let reason = "";
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed !== null && typeof parsed === "object") {
+                const e = parsed.error;
+                if (typeof e === "string")
+                    reason = e;
+            }
+        }
+        catch {
+            // Not JSON — fall back to the raw body below.
+        }
+        if (reason.trim().length === 0)
+            reason = body.trim().length > 0 ? body.trim() : "(no message)";
+        switch (status) {
+            case 401:
+                return new Errors_js_1.BurrowAuthException(reason);
+            case 403:
+                return new Errors_js_1.BurrowForbiddenException(reason);
+            case 404:
+                return new Errors_js_1.BurrowNotFoundException(reason);
+            default:
+                return new Errors_js_1.BurrowServerException(status, reason);
+        }
+    }
+}
+exports.Transport = Transport;
+/** Write the GET over an already-connected (and, for HTTPS, already-verified) socket and read the response. */
+function exchange(socket, url, headers) {
+    return new Promise((resolve, reject) => {
+        const req = (0, node_http_1.request)({
+            method: "GET",
+            // No agent, and createConnection hands back the socket we already dialled — host/port here only shape
+            // the request line, nothing is dialled again.
+            createConnection: () => socket,
+            host: url.hostname,
+            path: url.pathname + url.search,
+            headers: { ...headers, Accept: "application/json", Host: url.host },
+        });
+        req.setTimeout(TIMEOUT_MS, () => req.destroy(new Error(`timed out after ${TIMEOUT_MS}ms`)));
+        req.on("error", reject);
+        req.on("response", (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("error", reject);
+            res.on("end", () => resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString("utf8") }));
+        });
+        req.end();
+    });
+}
+function ignore() {
+    // Deliberately empty: see the note in Transport.connect.
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=Transport.js.map

package/dist/cjs/Transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transport.js","sourceRoot":"","sources":["../../src/Transport.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretShapeException = exports.FieldNotFoundException = exports.BurrowTransportException = exports.BurrowServerException = exports.BurrowNotFoundException = exports.BurrowIdentityException = exports.BurrowForbiddenException = exports.BurrowException = exports.BurrowCertificateException = exports.BurrowAuthException = exports.TlsMode = exports.MachineIdentity = exports.Identities = exports.SecretCoordinate = exports.Secret = exports.ProjectAccess = exports.SDK_VERSION = exports.DEFAULT_CLIENT_TAG = exports.Burrow = void 0;
+var Burrow_js_1 = require("./Burrow.js");
+Object.defineProperty(exports, "Burrow", { enumerable: true, get: function () { return Burrow_js_1.Burrow; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_TAG", { enumerable: true, get: function () { return Burrow_js_1.DEFAULT_CLIENT_TAG; } });
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return Burrow_js_1.SDK_VERSION; } });
+var Model_js_1 = require("./Model.js");
+Object.defineProperty(exports, "ProjectAccess", { enumerable: true, get: function () { return Model_js_1.ProjectAccess; } });
+Object.defineProperty(exports, "Secret", { enumerable: true, get: function () { return Model_js_1.Secret; } });
+Object.defineProperty(exports, "SecretCoordinate", { enumerable: true, get: function () { return Model_js_1.SecretCoordinate; } });
+var Identity_js_1 = require("./Identity.js");
+Object.defineProperty(exports, "Identities", { enumerable: true, get: function () { return Identity_js_1.Identities; } });
+Object.defineProperty(exports, "MachineIdentity", { enumerable: true, get: function () { return Identity_js_1.MachineIdentity; } });
+var Tls_js_1 = require("./Tls.js");
+Object.defineProperty(exports, "TlsMode", { enumerable: true, get: function () { return Tls_js_1.TlsMode; } });
+var Errors_js_1 = require("./Errors.js");
+Object.defineProperty(exports, "BurrowAuthException", { enumerable: true, get: function () { return Errors_js_1.BurrowAuthException; } });
+Object.defineProperty(exports, "BurrowCertificateException", { enumerable: true, get: function () { return Errors_js_1.BurrowCertificateException; } });
+Object.defineProperty(exports, "BurrowException", { enumerable: true, get: function () { return Errors_js_1.BurrowException; } });
+Object.defineProperty(exports, "BurrowForbiddenException", { enumerable: true, get: function () { return Errors_js_1.BurrowForbiddenException; } });
+Object.defineProperty(exports, "BurrowIdentityException", { enumerable: true, get: function () { return Errors_js_1.BurrowIdentityException; } });
+Object.defineProperty(exports, "BurrowNotFoundException", { enumerable: true, get: function () { return Errors_js_1.BurrowNotFoundException; } });
+Object.defineProperty(exports, "BurrowServerException", { enumerable: true, get: function () { return Errors_js_1.BurrowServerException; } });
+Object.defineProperty(exports, "BurrowTransportException", { enumerable: true, get: function () { return Errors_js_1.BurrowTransportException; } });
+Object.defineProperty(exports, "FieldNotFoundException", { enumerable: true, get: function () { return Errors_js_1.FieldNotFoundException; } });
+Object.defineProperty(exports, "SecretShapeException", { enumerable: true, get: function () { return Errors_js_1.SecretShapeException; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAsE;AAA7D,mGAAA,MAAM,OAAA;AAAE,+GAAA,kBAAkB,OAAA;AAAE,wGAAA,WAAW,OAAA;AAGhD,uCAAqE;AAA5D,yGAAA,aAAa,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAEhD,6CAA4D;AAAnD,yGAAA,UAAU,OAAA;AAAE,8GAAA,eAAe,OAAA;AACpC,mCAAmC;AAA1B,iGAAA,OAAO,OAAA;AAChB,yCAWqB;AAVnB,gHAAA,mBAAmB,OAAA;AACnB,uHAAA,0BAA0B,OAAA;AAC1B,4GAAA,eAAe,OAAA;AACf,qHAAA,wBAAwB,OAAA;AACxB,oHAAA,uBAAuB,OAAA;AACvB,oHAAA,uBAAuB,OAAA;AACvB,kHAAA,qBAAqB,OAAA;AACrB,qHAAA,wBAAwB,OAAA;AACxB,mHAAA,sBAAsB,OAAA;AACtB,iHAAA,oBAAoB,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/esm/Burrow.d.ts

@@ -0,0 +1,59 @@
+import { type BurrowClient } from "./BurrowClient.js";
+import { TlsMode } from "./Tls.js";
+/** The SDK version, reported in the `Ratel-Client` header for the Burrow's audit trail. */
+export declare const SDK_VERSION = "0.1.0";
+/** The default `Ratel-Client` tag. It contains "sdk", so the Burrow classifies reads as the SDK channel. */
+export declare const DEFAULT_CLIENT_TAG = "ratel-sdk-node/0.1.0";
+/** Options common to both ways of opening a client. */
+export interface BurrowOptions {
+    /** How to trust the Burrow's TLS certificate. Defaults to `TlsMode.Pinned` (trust-on-first-use). */
+    tls?: TlsMode;
+    /** The `Ratel-Client` tag recorded against each read. Defaults to {@link DEFAULT_CLIENT_TAG}. */
+    clientTag?: string;
+}
+/** Options for {@link Burrow.connect} — an explicit identity, no `~/.burrow` file involved. */
+export interface ConnectOptions extends BurrowOptions {
+    burrowUrl: string;
+    machineId: string;
+    /** The PKCS#8 PEM of the machine's Ed25519 private key. */
+    privateKeyPem: string;
+    /**
+     * The directory a `TlsMode.Pinned` trust-on-first-use pin is written into, as `known_cert`.
+     *
+     * One directory per Burrow, so an app connecting to two of them must give each its own — a shared
+     * directory would have the second overwrite the first's pin. Omitted keeps the pin in memory for the life
+     * of the client and writes nothing, which is what a container with no writable state wants; pass
+     * `TlsMode.PinnedTo` there instead, so trust does not restart from scratch on every boot.
+     */
+    pinStoreDir?: string;
+}
+/**
+ * Entry point for reading secrets from a Burrow with a machine identity.
+ *
+ * A machine is bootstrapped into a Burrow from its Machines page (the `curl | sh` install), which writes an
+ * identity under `~/.burrow`. From then on:
+ *
+ * ```ts
+ * const burrow = Burrow();                                  // the one identity on this host
+ * const db = await burrow.getSecret("payments/prod/DATABASE");
+ * const [user, pass] = db.getFields("username", "password");
+ * ```
+ *
+ * Point it at a specific identity by slug / name / machine id / URL, or by path:
+ *
+ * ```ts
+ * Burrow("burrow-a1b2c3d4e5f60718");                           // selector
+ * Burrow("/home/you/.burrow/burrows/burrow-a1b2c3d4e5f60718"); // path (dir or identity.json)
+ * ```
+ *
+ * For an app that ships its own key rather than the `~/.burrow` file, use {@link Burrow.connect}.
+ */
+export interface BurrowFactory {
+    (target?: string | null, options?: BurrowOptions): BurrowClient;
+    /** The default `Ratel-Client` tag. It contains "sdk", so the Burrow classifies reads as the SDK channel. */
+    readonly DEFAULT_CLIENT_TAG: string;
+    /** Connect with an explicit identity rather than one discovered under `~/.burrow`. */
+    connect(options: ConnectOptions): BurrowClient;
+}
+export declare const Burrow: BurrowFactory;
+//# sourceMappingURL=Burrow.d.ts.map

package/dist/esm/Burrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Burrow.d.ts","sourceRoot":"","sources":["../../src/Burrow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAuB,MAAM,mBAAmB,CAAC;AAE3E,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,2FAA2F;AAC3F,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,yBAAkC,CAAC;AAElE,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,oGAAoG;IACpG,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,iGAAiG;IACjG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;IAEhE,4GAA4G;IAC5G,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAEpC,sFAAsF;IACtF,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CAAC;CAChD;AAED,eAAO,MAAM,MAAM,EAAE,aAAoE,CAAC"}

package/dist/esm/Burrow.js

@@ -0,0 +1,27 @@
+import { DefaultBurrowClient } from "./BurrowClient.js";
+import { Identities, parseEd25519PrivateKey } from "./Identity.js";
+import { TlsMode } from "./Tls.js";
+/** The SDK version, reported in the `Ratel-Client` header for the Burrow's audit trail. */
+export const SDK_VERSION = "0.1.0";
+/** The default `Ratel-Client` tag. It contains "sdk", so the Burrow classifies reads as the SDK channel. */
+export const DEFAULT_CLIENT_TAG = `ratel-sdk-node/${SDK_VERSION}`;
+/**
+ * Open a client. `target` is one of:
+ *  - omitted — the single identity on this host (under `~/.burrow`, or `$BURROW_HOME`);
+ *  - a selector — a burrow slug, name, machine id, or URL;
+ *  - a filesystem path — a burrow identity directory or an `identity.json` file.
+ */
+function open(target, options = {}) {
+    const id = Identities.select(target);
+    return new DefaultBurrowClient(id.burrowUrl, id.machineId, id.loadPrivateKey(), options.clientTag ?? DEFAULT_CLIENT_TAG, options.tls ?? TlsMode.Pinned, id.directory);
+}
+/**
+ * Connect with an explicit identity — for an app that manages its own key material rather than reading the
+ * `~/.burrow` file.
+ */
+function connect(options) {
+    const key = parseEd25519PrivateKey(options.privateKeyPem, "provided PEM");
+    return new DefaultBurrowClient(options.burrowUrl, options.machineId, key, options.clientTag ?? DEFAULT_CLIENT_TAG, options.tls ?? TlsMode.Pinned, options.pinStoreDir ?? null);
+}
+export const Burrow = Object.assign(open, { DEFAULT_CLIENT_TAG, connect });
+//# sourceMappingURL=Burrow.js.map

package/dist/esm/Burrow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Burrow.js","sourceRoot":"","sources":["../../src/Burrow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,4GAA4G;AAC5G,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,WAAW,EAAE,CAAC;AA2BlE;;;;;GAKG;AACH,SAAS,IAAI,CAAC,MAAsB,EAAE,UAAyB,EAAE;IAC/D,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,OAAO,IAAI,mBAAmB,CAC5B,EAAE,CAAC,SAAS,EACZ,EAAE,CAAC,SAAS,EACZ,EAAE,CAAC,cAAc,EAAE,EACnB,OAAO,CAAC,SAAS,IAAI,kBAAkB,EACvC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,MAAM,EAC7B,EAAE,CAAC,SAAS,CACb,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,OAAO,CAAC,OAAuB;IACtC,MAAM,GAAG,GAAG,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAC1E,OAAO,IAAI,mBAAmB,CAC5B,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,SAAS,EACjB,GAAG,EACH,OAAO,CAAC,SAAS,IAAI,kBAAkB,EACvC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,MAAM,EAC7B,OAAO,CAAC,WAAW,IAAI,IAAI,CAC5B,CAAC;AACJ,CAAC;AAiCD,MAAM,CAAC,MAAM,MAAM,GAAkB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC"}