@ratelkey/burrow-sdk 0.1.0

package/dist/esm/Model.d.ts

@@ -0,0 +1,75 @@
+/** One field of a structured secret: its name, current plaintext value, and declared type. */
+export interface SecretField {
+    readonly name: string;
+    readonly value: string;
+    readonly type: string;
+}
+/**
+ * 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}.
+ */
+export declare class Secret {
+    /** The secret's name (the final segment of its `project/env/NAME` coordinate). */
+    readonly name: string;
+    private readonly singleValue;
+    private readonly singleType;
+    private readonly singleVersion;
+    private readonly fieldsByName;
+    private constructor();
+    /** True when this is a structured (multi-field) secret rather than a single value. */
+    get isStructured(): boolean;
+    /** The single value. Throws {@link SecretShapeException} if this is a structured secret. */
+    get value(): string;
+    /** The declared type of a single-value secret; null for a structured one. */
+    get type(): string | null;
+    /** The current version of a single-value secret; null for a structured one. */
+    get version(): number | null;
+    /** Every field as a name → value map. Throws {@link SecretShapeException} if this is a single-value secret. */
+    toMap(): Record<string, string>;
+    /** The typed fields. Throws {@link SecretShapeException} if this is a single-value secret. */
+    fields(): SecretField[];
+    /**
+     * One field's value. Throws {@link SecretShapeException} if single-value, or
+     * {@link FieldNotFoundException} if absent.
+     */
+    getField(field: string): string;
+    /**
+     * 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: string[]): string[];
+    private structured;
+    /** @internal */
+    static single(name: string, value: string, type: string, version: number): Secret;
+    /** @internal */
+    static structured(name: string, fields: ReadonlyMap<string, SecretField>): Secret;
+}
+/** A secret this machine can read, addressed by its `project / env / name` coordinate. */
+export declare class SecretCoordinate {
+    readonly project: string;
+    readonly environment: string;
+    readonly name: string;
+    constructor(project: string, environment: string, name: string);
+    /** The `project/env/NAME` slug form, as the Burrow lists it and `BurrowClient.getSecret` takes it. */
+    toString(): string;
+    /** Parse a `project/env/NAME` slug into its parts. */
+    static parse(slug: string): SecretCoordinate;
+}
+/** A project this machine can read, and the environment categories it holds a grant for. */
+export declare class ProjectAccess {
+    readonly project: string;
+    readonly categories: readonly string[];
+    constructor(project: string, categories: readonly string[]);
+}
+//# sourceMappingURL=Model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Model.d.ts","sourceRoot":"","sources":["../../src/Model.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IAEf,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAN/B,OAAO;IASP,sFAAsF;IACtF,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,4FAA4F;IAC5F,IAAI,KAAK,IAAI,MAAM,CAOlB;IAED,6EAA6E;IAC7E,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI,CAExB;IAED,+EAA+E;IAC/E,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,+GAA+G;IAC/G,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAM/B,8FAA8F;IAC9F,MAAM,IAAI,WAAW,EAAE;IAIvB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAO/B;;;;OAIG;IACH,SAAS,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IASvC,OAAO,CAAC,UAAU;IAOlB,gBAAgB;IAChB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAIjF,gBAAgB;IAChB,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM;CAGlF;AAED,0FAA0F;AAC1F,qBAAa,gBAAgB;IAEzB,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAFZ,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM;IAGvB,sGAAsG;IACtG,QAAQ,IAAI,MAAM;IAIlB,sDAAsD;IACtD,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB;CAa7C;AAED,4FAA4F;AAC5F,qBAAa,aAAa;IAEtB,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE;gBAD7B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,SAAS,MAAM,EAAE;CAEzC"}

package/dist/esm/Model.js

@@ -0,0 +1,137 @@
+import { FieldNotFoundException, SecretShapeException } from "./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}.
+ */
+export 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 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 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 FieldNotFoundException(this.name, n, f.keys());
+            return hit.value;
+        });
+    }
+    structured() {
+        if (this.fieldsByName === null) {
+            throw new 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);
+    }
+}
+/** A secret this machine can read, addressed by its `project / env / name` coordinate. */
+export 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));
+    }
+}
+/** A project this machine can read, and the environment categories it holds a grant for. */
+export class ProjectAccess {
+    project;
+    categories;
+    constructor(project, categories) {
+        this.project = project;
+        this.categories = categories;
+    }
+}
+//# sourceMappingURL=Model.js.map

package/dist/esm/Model.js.map

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

package/dist/esm/Signer.d.ts

@@ -0,0 +1,19 @@
+import { type KeyObject } from "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).
+ */
+export declare const MachineSigner: {
+    canonical(action: string, resource: readonly string[], timestamp: string, nonce: string, client: string): Buffer;
+    /** The signed `Ratel-*` headers for one request. */
+    sign(machineId: string, key: KeyObject, action: string, resource: readonly string[], client: string, nowMillis: number): Record<string, string>;
+};
+//# sourceMappingURL=Signer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Signer.d.ts","sourceRoot":"","sources":["../../src/Signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAkC,MAAM,aAAa,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa;sBAEd,MAAM,YACJ,SAAS,MAAM,EAAE,aAChB,MAAM,SACV,MAAM,UACL,MAAM,GACb,MAAM;IAOT,oDAAoD;oBAEvC,MAAM,OACZ,SAAS,UACN,MAAM,YACJ,SAAS,MAAM,EAAE,UACnB,MAAM,aACH,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAmB1B,CAAC"}

package/dist/esm/Signer.js

@@ -0,0 +1,39 @@
+import { randomBytes, sign as signBytes } from "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).
+ */
+export const 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 = randomBytes(16).toString("base64");
+        // Ed25519 signs the message directly: the digest algorithm must be null, not a hash name.
+        const signature = signBytes(null, 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/esm/Signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Signer.js","sourceRoot":"","sources":["../../src/Signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,WAAW,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,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,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjD,0FAA0F;QAC1F,MAAM,SAAS,GAAG,SAAS,CACzB,IAAI,EACJ,aAAa,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/esm/Tls.d.ts

@@ -0,0 +1,71 @@
+/** How the SDK establishes trust in the Burrow's TLS certificate. */
+export type TlsMode = 
+/**
+ * Trust-on-first-use. Burrows serve HTTPS self-signed by default, so there is no public CA to verify
+ * against — instead the Burrow's public key is pinned on first contact and a changed key is refused
+ * afterwards (like SSH host keys). The key rather than the certificate, so a Burrow that adds a domain or
+ * renews its certificate stays the same Burrow. The pin is kept beside that Burrow's identity, at
+ * `~/.burrow/burrows/<slug>/known_cert`, shared with the `ratel` CLI. This is the default and works with
+ * an out-of-box Burrow.
+ */
+{
+    readonly kind: "pinned";
+}
+/**
+ * Pin to a specific key fingerprint: the SHA-256 of the Burrow's public key as it shows in its network
+ * settings (lowercase colon-separated hex; colons and case are ignored on comparison). No first-use
+ * trust — the key must match from the very first request.
+ */
+ | {
+    readonly kind: "pinnedTo";
+    readonly fingerprint: string;
+}
+/**
+ * Standard trust: verify the certificate against the system CA store and the hostname. Use this when
+ * the Burrow serves a CA-issued certificate (a custom domain, or automatic Let's Encrypt).
+ */
+ | {
+    readonly kind: "systemTrust";
+};
+/** The three trust modes, as values: `TlsMode.Pinned`, `TlsMode.PinnedTo("aa:bb:…")`, `TlsMode.SystemTrust`. */
+export declare const TlsMode: {
+    readonly Pinned: TlsMode;
+    readonly PinnedTo: (fingerprint: string) => TlsMode;
+    readonly SystemTrust: TlsMode;
+};
+/**
+ * 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.
+ */
+export declare function publicKeyPin(der: Uint8Array): string;
+/** Compare two fingerprints ignoring case and separators, so "AA:BB…" and "aabb…" match. */
+export declare function fingerprintsEqual(a: string, b: string): boolean;
+/**
+ * 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.
+ */
+export declare class PinStore {
+    private readonly file;
+    constructor(dir: string | null);
+    read(): string | null;
+    write(pin: string): void;
+}
+//# sourceMappingURL=Tls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Tls.d.ts","sourceRoot":"","sources":["../../src/Tls.ts"],"names":[],"mappings":"AAIA,qEAAqE;AACrE,MAAM,MAAM,OAAO;AACjB;;;;;;;GAOG;AACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AAC7B;;;;GAIG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AAC7D;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAErC,gHAAgH;AAChH,eAAO,MAAM,OAAO;qBACY,OAAO;qCACb,MAAM,KAAG,OAAO;0BACA,OAAO;CACvC,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAI/D;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;gBAEzB,GAAG,EAAE,MAAM,GAAG,IAAI;IAI9B,IAAI,IAAI,MAAM,GAAG,IAAI;IASrB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAazB"}

package/dist/esm/Tls.js

@@ -0,0 +1,79 @@
+import { createHash, X509Certificate } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** The three trust modes, as values: `TlsMode.Pinned`, `TlsMode.PinnedTo("aa:bb:…")`, `TlsMode.SystemTrust`. */
+export const 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.
+ */
+export function publicKeyPin(der) {
+    const spki = new X509Certificate(Buffer.from(der)).publicKey.export({ type: "spki", format: "der" });
+    const hex = createHash("sha256").update(spki).digest("hex");
+    return (hex.match(/../g) ?? []).join(":");
+}
+/** Compare two fingerprints ignoring case and separators, so "AA:BB…" and "aabb…" match. */
+export 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.
+ */
+export class PinStore {
+    file;
+    constructor(dir) {
+        this.file = dir === null ? null : join(dir, "known_cert");
+    }
+    read() {
+        if (this.file === null)
+            return null;
+        try {
+            return 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 {
+            mkdirSync(dirname(this.file), { recursive: true });
+            const tmp = `${this.file}.tmp`;
+            writeFileSync(tmp, `${pin}\n`);
+            renameSync(tmp, this.file);
+        }
+        catch {
+            // ignored
+        }
+    }
+}
+//# sourceMappingURL=Tls.js.map

package/dist/esm/Tls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tls.js","sourceRoot":"","sources":["../../src/Tls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAyB1C,gHAAgH;AAChH,MAAM,CAAC,MAAM,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,MAAM,UAAU,YAAY,CAAC,GAAe;IAC1C,MAAM,IAAI,GAAG,IAAI,eAAe,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,UAAU,CAAC,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,MAAM,UAAU,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,MAAM,OAAO,QAAQ;IACF,IAAI,CAAgB;IAErC,YAAY,GAAkB;QAC5B,IAAI,CAAC,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,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,YAAY,CAAC,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,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,MAAM,CAAC;YAC/B,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,CAAC;YAC/B,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,UAAU;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/esm/Transport.d.ts

@@ -0,0 +1,29 @@
+import { type TlsMode } from "./Tls.js";
+/**
+ * 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.
+ */
+export declare class Transport {
+    private readonly tls;
+    private readonly base;
+    private readonly pins;
+    /** The fingerprint currently enforced. Null in trust-on-first-use mode until the first pin is learned. */
+    private pinned;
+    constructor(burrowUrl: string, tls: TlsMode, 
+    /** This Burrow's identity directory — where its pinned key lives, beside the key that signs for it. */
+    identityDir: string | null);
+    /** Signed GET, returning the response body on 2xx; throws a typed {@link BurrowException} otherwise. */
+    get(path: string, headers: Record<string, string>): Promise<string>;
+    private resolve;
+    /** Dial the Burrow and, for the pinned modes, verify its certificate before anything is written. */
+    private connect;
+    private commitPinIfNew;
+    private errorFor;
+}
+//# sourceMappingURL=Transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Transport.d.ts","sourceRoot":"","sources":["../../src/Transport.ts"],"names":[],"mappings":"AAaA,OAAO,EAA6C,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAUnF;;;;;;;;;GASG;AACH,qBAAa,SAAS;IAQlB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,0GAA0G;IAC1G,OAAO,CAAC,MAAM,CAAgB;gBAG5B,SAAS,EAAE,MAAM,EACA,GAAG,EAAE,OAAO;IAC7B,uGAAuG;IACvG,WAAW,EAAE,MAAM,GAAG,IAAI;IAO5B,wGAAwG;IAClG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBzE,OAAO,CAAC,OAAO;IAgBf,oGAAoG;IACpG,OAAO,CAAC,OAAO;IAiFf,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,QAAQ;CAuBjB"}