@zincapp/znvault-cli 4.22.1 → 4.24.0

package/dist/lib/restore-drill.js

@@ -0,0 +1,185 @@
+// Path: src/lib/restore-drill.ts
+//
+// The two gates of the isolated-restore drill.
+//
+// THE DRILL'S FAILURE MODE IS SUCCESS. If the restored database ends up with no
+// LMK version above zero, `initializeFromPG()` reads "no ACTIVE version" and
+// takes the legitimate first-boot path: `bootstrapInitialLMKVersion()` mints a
+// brand-new LMK, wraps it under the bootstrap key on disk, inserts version 1,
+// and the vault comes up healthy. `/v1/health` answers 200 with `status: 'ok'`
+// and a root key whose KCV even MATCHES the escrow bundle — the BSK really was
+// restored from it. Every signal an operator would look at says the drill
+// passed. What actually happened is that a new key hierarchy was created over
+// an empty database, and the only thing the drill exists to demonstrate — that
+// this bundle brings back THIS deployment's keys — was never exercised.
+//
+// So neither gate may read an exit code or an HTTP status. Degraded root-key
+// resolution returns 200 with the degradation reported inside the body, and a
+// null resolution state omits the `rootKey` block entirely while still
+// returning 200 and `status: 'ok'`. Both gates read state and compare it
+// against what the bundle says, and both explain themselves: a failed drill is
+// investigated cold, hours later, by someone who was not there.
+//
+// Pure functions on purpose. The orchestration around them drives docker from a
+// shell script and cannot be unit-tested, so everything that DECIDES anything
+// lives here where it can be.
+/**
+ * Versions at or below zero are not real key generations.
+ *
+ * `models.postgres.sql` seeds `version=0, status='ACTIVE',
+ * key_id='ZK_MODE_PLACEHOLDER'` on every boot. Counting it would make a
+ * correctly restored database look like it has two ACTIVE versions.
+ */
+function positives(versions) {
+    return versions.filter((v) => v.version > 0);
+}
+function describe(versions) {
+    const rows = positives(versions);
+    if (rows.length === 0)
+        return '(no versions above zero)';
+    return rows
+        .map((v) => `v${String(v.version)} ${v.status}${v.hasWrappedLmk ? '' : ' [no material]'}`)
+        .join(', ');
+}
+/**
+ * Gate 1, run BEFORE the vault is started against the restored database.
+ *
+ * Before, not after, because once the vault mints a replacement LMK the
+ * evidence of what went wrong is overwritten: the table then holds a perfectly
+ * ordinary version 1 with material, and nothing distinguishes it from a
+ * successful restore except that it is the wrong key.
+ *
+ * @throws with a diagnosis whenever the database could not have come from the
+ *   deployment the bundle describes.
+ */
+export function assertRestoredDatabaseIsRecoverable(versions, expectedActiveVersion) {
+    const rows = positives(versions);
+    if (rows.length === 0) {
+        throw new Error('The restored database holds no LMK version above zero. Starting a vault ' +
+            'against it would NOT fail: it would take the first-boot path, MINT a new ' +
+            'LMK, and report a completely healthy start — the drill would pass having ' +
+            'restored nothing. Check that the database dump was actually applied and ' +
+            'that it came from the same snapshot as the escrow bundle.');
+    }
+    const recoverable = rows.filter((v) => v.hasWrappedLmk);
+    if (recoverable.length === 0) {
+        throw new Error(`The restored database holds ${String(rows.length)} LMK version(s) above zero ` +
+            `but none has wrapped material (${describe(versions)}). The inventory came ` +
+            'back and the key material did not, which reaches the same mint-a-new-key ' +
+            'path as an empty table.');
+    }
+    const actives = rows.filter((v) => v.status === 'ACTIVE');
+    if (actives.length !== 1) {
+        throw new Error(`The restored database has ${String(actives.length)} ACTIVE LMK version(s) ` +
+            `above zero (${describe(versions)}); exactly one is required. A drill run ` +
+            'against an ambiguous key state proves nothing about either version.');
+    }
+    const active = actives.at(0);
+    if (active === undefined)
+        throw new Error('unreachable: one ACTIVE row expected');
+    if (!active.hasWrappedLmk) {
+        throw new Error(`The ACTIVE LMK version ${String(active.version)} has no wrapped material. ` +
+            'The vault cannot unwrap the current key from this database.');
+    }
+    if (active.version !== expectedActiveVersion) {
+        throw new Error(`The restored database is ACTIVE on LMK version ${String(active.version)}, but ` +
+            `the escrow bundle was taken when version ${String(expectedActiveVersion)} was ` +
+            'active. The bundle and the dump are from different moments, so a successful ' +
+            'boot would say nothing about either of them.');
+    }
+}
+/**
+ * Gate 2, run AFTER the vault has started.
+ *
+ * Confirms three separate things, because each can be true while the others are
+ * not: the node resolved the key the bundle carries, it did so cleanly, and it
+ * did NOT create anything new to do it.
+ *
+ * WHAT THIS GATE CANNOT DO, measured on a bench rather than assumed. A vault
+ * started against an empty database mints LMK version 1 and reports
+ * `status: ok` with a root-key KCV that MATCHES the bundle — the bootstrap key
+ * really did come from it. If the bundle's own active version happens to be 1,
+ * every field checked below is correct and the mint passes. Production is on
+ * version 4 today, so this gate would catch it there; that is luck, not design.
+ * `assertRestoredDatabaseIsRecoverable` is what actually closes it, which is
+ * why the pre-boot gate is never "the one the post gate makes redundant".
+ *
+ * @throws with both values named whenever a comparison fails.
+ */
+export function assertBootedOnRestoredKeys(input) {
+    const { health, versionsAfterBoot, expectedBskKcv, expectedActiveVersion } = input;
+    // A null resolution state omits the block and still answers 200 with
+    // status 'ok'. Reading `health.rootKey?.kcv` into a comparison would compare
+    // `undefined` and quietly skip the only check that matters.
+    const rootKey = health.rootKey;
+    if (rootKey === undefined || typeof rootKey.kcv !== 'string' || rootKey.kcv === '') {
+        throw new Error('The health body carries no rootKey block, so there is nothing to compare ' +
+            'against the escrow bundle. This is what a null root-key resolution state ' +
+            'looks like from outside — HTTP 200, status "ok", and no answer to the only ' +
+            'question the drill asked.');
+    }
+    if (rootKey.degraded === true) {
+        throw new Error(`The node resolved a root key (${rootKey.kcv}) but reports DEGRADED: at least ` +
+            'one configured provider failed. On a drill whose whole point is "the ' +
+            'escrowed key opens this database", a partial answer is not an answer.');
+    }
+    if (rootKey.kcv !== expectedBskKcv) {
+        throw new Error('The node booted on a DIFFERENT bootstrap key than the escrow bundle ' +
+            `carries. Bundle: ${expectedBskKcv}. Running node: ${rootKey.kcv}. ` +
+            'Either the key file was not restored from this bundle, or another ' +
+            'root-key provider answered first.');
+    }
+    const actives = positives(versionsAfterBoot).filter((v) => v.status === 'ACTIVE');
+    const active = actives.at(0);
+    if (actives.length !== 1 || active === undefined) {
+        throw new Error(`After boot the database has ${String(actives.length)} ACTIVE LMK version(s) ` +
+            `above zero (${describe(versionsAfterBoot)}); exactly one is required.`);
+    }
+    if (active.version !== expectedActiveVersion) {
+        throw new Error(`After boot the vault is ACTIVE on LMK version ${String(active.version)}, not ` +
+            `the version ${String(expectedActiveVersion)} the escrow bundle was taken at. ` +
+            'The most likely cause is that the vault MINTED a new LMK because it found ' +
+            'nothing to load — which produces a healthy-looking node running on a key ' +
+            'that was created seconds ago and exists nowhere else. ' +
+            `Versions now: ${describe(versionsAfterBoot)}.`);
+    }
+}
+/**
+ * Refuse to run the drill against anything that is not on this machine.
+ *
+ * The drill reads a database and then asserts things about a vault; both
+ * halves are harmless. What is not harmless is running it with a production
+ * URL by accident — the pre-boot gate would report a green production, the
+ * post-boot gate would compare production's KCV against an escrow bundle, and
+ * the whole exercise would be recorded as a successful restore drill without a
+ * single byte having been restored. That is the same false green the gates
+ * exist to remove, arriving through the front door.
+ *
+ * Hostname only. Anything that resolves elsewhere at runtime (a name pointing
+ * at a remote address, an SSH tunnel) is out of scope for a lab guard, and
+ * pretending otherwise would be worse than saying so.
+ *
+ * @throws when the target host is not loopback.
+ */
+export function assertIsolatedTarget(rawUrl, what) {
+    let host;
+    try {
+        host = new URL(rawUrl).hostname;
+    }
+    catch {
+        throw new Error(`The ${what} is not a valid URL: ${rawUrl}`);
+    }
+    // `new URL().hostname` KEEPS the brackets on an IPv6 literal — `[::1]`, not
+    // `::1`. Comparing against the bare form silently rejects a legitimate
+    // loopback bench, which is the kind of guard people disable rather than fix.
+    const bare = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    const loopback = bare === 'localhost' || bare === '::1' || bare.startsWith('127.');
+    if (!loopback) {
+        throw new Error(`Refusing to run the restore drill against ${what} host "${host}". The drill ` +
+            'is only meaningful on an isolated bench: pointed at a live deployment it ' +
+            'would compare that deployment against the escrow bundle and record a ' +
+            'successful "restore" in which nothing was restored. Use a loopback ' +
+            'address on the bench host.');
+    }
+}
+//# sourceMappingURL=restore-drill.js.map

package/dist/lib/restore-drill.js.map

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

package/dist/lib/sentinel-client.d.ts

@@ -0,0 +1,26 @@
+export interface SentinelClientConfig {
+    /** Base URL of the appliance. https:// only. */
+    url: string;
+    /** CA bundle that must issue the appliance's certificate. */
+    caPath: string;
+    /** Client certificate presented to the appliance. */
+    certPath: string;
+    /** Its private key. */
+    keyPath: string;
+    timeoutMs?: number;
+}
+export interface SentinelClient {
+    /** Open an envelope. Returns a fresh 32-byte buffer the caller must wipe. */
+    unwrap(envelope: Buffer): Promise<Buffer>;
+    /** Liveness plus a KCV claim. No plaintext crosses the wire. */
+    probe(envelope: Buffer): Promise<string>;
+}
+/**
+ * Build the client. Reads the certificate material eagerly so a missing or
+ * unreadable file fails now — at the top of a ceremony, with everything still
+ * locked — rather than at the moment the key is expected to arrive.
+ *
+ * @throws on a non-https URL or unreadable certificate material.
+ */
+export declare function createSentinelClient(config: SentinelClientConfig): SentinelClient;
+//# sourceMappingURL=sentinel-client.d.ts.map

package/dist/lib/sentinel-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel-client.d.ts","sourceRoot":"","sources":["../../src/lib/sentinel-client.ts"],"names":[],"mappings":"AAuDA,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,gEAAgE;IAChE,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAuHjF"}

package/dist/lib/sentinel-client.js

@@ -0,0 +1,165 @@
+// Path: src/lib/sentinel-client.ts
+//
+// Minimal mTLS JSON client for the Archon Sentinel appliance, so an escrow
+// ceremony can source the bootstrap key from the hardware root instead of from
+// a cleartext file on a production node.
+//
+// PORT NOTICE. This is a SECOND implementation of a protocol the server already
+// speaks in zn-vault/src/vault-crypto/root-key/sentinel-adapter.ts. This package
+// ships to npm on its own and cannot import from the server, so the protocol
+// necessarily exists twice — normally the way a contract dies quietly, with both
+// suites green and the two sides agreeing on nothing.
+//
+// The defence is the one used for `kcv1:`: neither side is checked against the
+// other. Both are pinned to frozen literals — paths, field names, encoding —
+// in test/lib/sentinel-client.test.ts here and in the adapter's own suite there.
+// Rename a field on either side and both go red.
+//
+// The wire, copied verbatim from the server adapter's header:
+//
+//   POST /v1/root/unwrap  {"envelope":"<b64>"}  -> 200 {"plaintext":"<b64>"}
+//   POST /v1/root/probe   {"envelope":"<b64>"}  -> 200 {"kcv":"kcv1:..."}
+//
+// DELIBERATELY NOT IMPLEMENTED: `wrap`. Its request body carries the bootstrap
+// key, and provisioning a new root is a server-side operation with its own
+// audit trail (`znvault superadmin rootkey wrap`). A ceremony host has no
+// business minting envelopes, so the capability is simply absent rather than
+// present-and-guarded.
+import { request } from 'node:https';
+import { readFileSync } from 'node:fs';
+/** Frozen wire paths. Pinned as literals in the test suite. */
+const OP_PATHS = {
+    unwrap: '/v1/root/unwrap',
+    probe: '/v1/root/probe',
+};
+/**
+ * The purpose this client asks for, sent EXPLICITLY.
+ *
+ * Protocol v1.1 binds a purpose into the envelope's cryptography so a KMIP KEK
+ * envelope can never be opened as if it were the vault's bootstrap key. The
+ * field is optional and defaults to this same value — but the daemon's own
+ * comment calls that default a "staged rollout" affordance, there so the
+ * pre-purpose vault keeps booting during the migration.
+ *
+ * New code written today has no business depending on a compatibility default
+ * that exists to be removed. Sending it also makes the ask readable on the
+ * wire, which matters when the wire is being watched during a key ceremony.
+ */
+const BSK_PURPOSE = 'zn-vault-bsk-v1';
+const BSK_LEN = 32;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+/**
+ * Build the client. Reads the certificate material eagerly so a missing or
+ * unreadable file fails now — at the top of a ceremony, with everything still
+ * locked — rather than at the moment the key is expected to arrive.
+ *
+ * @throws on a non-https URL or unreadable certificate material.
+ */
+export function createSentinelClient(config) {
+    const target = new URL(config.url);
+    if (target.protocol !== 'https:') {
+        // The unwrap response carries the bootstrap key. There is no version of
+        // this that may travel in clear, and a typo in a runbook must not be what
+        // decides it.
+        throw new Error(`The Sentinel URL must be https://, got ${JSON.stringify(config.url)}. ` +
+            'The unwrap response carries the bootstrap key.');
+    }
+    const tls = {
+        ca: readFileSync(config.caPath),
+        cert: readFileSync(config.certPath),
+        key: readFileSync(config.keyPath),
+    };
+    const basePath = target.pathname.replace(/\/+$/, '');
+    const timeoutMs = config.timeoutMs ?? 5000;
+    async function call(op, payload) {
+        const body = Buffer.from(JSON.stringify(payload), 'utf-8');
+        return await new Promise((resolve, reject) => {
+            const req = request({
+                method: 'POST',
+                protocol: target.protocol,
+                hostname: target.hostname,
+                port: target.port,
+                path: `${basePath}${OP_PATHS[op]}`,
+                headers: { 'content-type': 'application/json', 'content-length': body.length },
+                ca: tls.ca,
+                cert: tls.cert,
+                key: tls.key,
+                // Left at its default (true) on purpose. The CA above is the pin:
+                // without it Node would validate against the public root store and
+                // accept a certificate this deployment never issued — the wrong
+                // check, not a weaker one.
+                timeout: timeoutMs,
+            }, (res) => {
+                const chunks = [];
+                let total = 0;
+                res.on('data', (chunk) => {
+                    total += chunk.length;
+                    if (total > MAX_RESPONSE_BYTES) {
+                        req.destroy(new Error(`Sentinel ${op} response exceeded ${String(MAX_RESPONSE_BYTES)} bytes`));
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                res.on('end', () => {
+                    const status = res.statusCode ?? 0;
+                    const raw = Buffer.concat(chunks).toString('utf-8');
+                    if (status < 200 || status >= 300) {
+                        reject(new Error(`Sentinel ${op} failed: HTTP ${String(status)}`));
+                        return;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        reject(new Error(`Sentinel ${op} returned HTTP ${String(status)} with a malformed JSON body`));
+                        return;
+                    }
+                    if (typeof parsed !== 'object' || parsed === null) {
+                        reject(new Error(`Sentinel ${op} returned a JSON value that is not an object`));
+                        return;
+                    }
+                    resolve(parsed);
+                });
+            });
+            req.on('timeout', () => {
+                req.destroy(new Error(`Sentinel ${op} timed out after ${String(timeoutMs)}ms`));
+            });
+            req.on('error', reject);
+            req.end(body);
+        });
+    }
+    return {
+        async unwrap(envelope) {
+            const response = await call('unwrap', {
+                envelope: envelope.toString('base64'),
+                purpose: BSK_PURPOSE,
+            });
+            const plaintext = response.plaintext;
+            if (typeof plaintext !== 'string') {
+                throw new Error('Sentinel unwrap returned 200 without a string "plaintext" field. ' +
+                    'Something answered that is not the appliance protocol — a proxy, a ' +
+                    'captive portal, or a mismatched appliance version.');
+            }
+            const key = Buffer.from(plaintext, 'base64');
+            if (key.length !== BSK_LEN) {
+                key.fill(0);
+                throw new Error(`Sentinel unwrap returned ${String(key.length)} bytes; a bootstrap key is ` +
+                    `exactly ${String(BSK_LEN)} bytes.`);
+            }
+            return key;
+        },
+        async probe(envelope) {
+            const response = await call('probe', {
+                envelope: envelope.toString('base64'),
+                purpose: BSK_PURPOSE,
+            });
+            const kcv = response.kcv;
+            if (typeof kcv !== 'string') {
+                throw new Error('Sentinel probe returned 200 without a string "kcv" field.');
+            }
+            return kcv;
+        },
+    };
+}
+//# sourceMappingURL=sentinel-client.js.map

package/dist/lib/sentinel-client.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zincapp/znvault-cli",
-  "version": "4.22.1",
+  "version": "4.24.0",
   "description": "Official CLI for ZnVault administration",
   "type": "module",
   "main": "dist/index.js",