@zincapp/znvault-cli 4.22.1 → 4.24.0

package/dist/lib/db/key-lifecycle.d.ts

@@ -0,0 +1,86 @@
+import { BaseDBClient } from './client.js';
+export type CeremonyPhase = 'preflight' | 'workspace' | 'material' | 'write-a' | 'write-b' | 'verify' | 'teardown';
+export interface PhaseEvent {
+    seq: number;
+    phase: string;
+    state: string;
+    at: string;
+    detail: Record<string, unknown> | null;
+}
+export interface LifecycleOperation {
+    operationId: string;
+    kind: string;
+    state: string;
+    phase: string;
+    epoch: number;
+    ownerNodeId: string;
+    ownerPrincipal: string;
+    minRelease: string;
+    startedAt: string;
+    finishedAt: string | null;
+    lastError: string | null;
+}
+export declare class KeyLifecycleOperations extends BaseDBClient {
+    /**
+     * Is the schema present?
+     *
+     * The CLI ships independently of the server, so it can meet a deployment that
+     * predates migration 093. Saying so plainly beats a `relation does not exist`
+     * in the middle of a ceremony.
+     */
+    schemaPresent(): Promise<boolean>;
+    /** The operation currently holding the exclusion slot, if any. */
+    active(): Promise<LifecycleOperation | null>;
+    /**
+     * Start a ceremony, or find out who already holds the slot.
+     *
+     * Does NOT look before it leaps: a "is anything running?" SELECT followed by
+     * an INSERT is exactly the race the index exists to close. The INSERT is the
+     * check, and 23505 is the answer.
+     */
+    claim(input: {
+        phase: CeremonyPhase;
+        ownerNodeId: string;
+        ownerPrincipal: string;
+        minRelease: string;
+        detail?: Record<string, unknown>;
+    }): Promise<{
+        ok: true;
+        operation: LifecycleOperation;
+    } | {
+        ok: false;
+        active: LifecycleOperation | null;
+    }>;
+    /**
+     * Move to the next phase, recording it in the same transaction.
+     *
+     * Compare-and-swap on `epoch`: a caller holding a stale read is refused
+     * rather than silently overwriting whoever moved first.
+     */
+    advance(input: {
+        operationId: string;
+        expectedEpoch: number;
+        phase: CeremonyPhase;
+        nodeId: string;
+        detail?: Record<string, unknown>;
+    }): Promise<LifecycleOperation>;
+    /**
+     * Close the operation, releasing the slot.
+     *
+     * `ABANDONED` is a real transition with a reason rather than a DELETE: why a
+     * ceremony was abandoned is exactly what the next person needs to read, and a
+     * global exclusion with no escape hatch is a deadlock waiting for its first
+     * interrupted ceremony.
+     */
+    finish(input: {
+        operationId: string;
+        expectedEpoch: number;
+        outcome: 'COMPLETED' | 'FAILED' | 'ABANDONED';
+        nodeId: string;
+        error?: string;
+        detail?: Record<string, unknown>;
+    }): Promise<LifecycleOperation>;
+    /** The full route travelled, oldest first. */
+    history(operationId: string): Promise<PhaseEvent[]>;
+}
+//# sourceMappingURL=key-lifecycle.d.ts.map

package/dist/lib/db/key-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/lib/db/key-lifecycle.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,WAAW,GACX,UAAU,GACV,SAAS,GACT,SAAS,GACT,QAAQ,GACR,UAAU,CAAC;AAEf,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAsCD,qBAAa,sBAAuB,SAAQ,YAAY;IACtD;;;;;;OAMG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAQvC,kEAAkE;IAC5D,MAAM,IAAI,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IASlD;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE;QACjB,KAAK,EAAE,aAAa,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,kBAAkB,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAA;KAAE,CAAC;IAgC3G;;;;;OAKG;IACG,OAAO,CAAC,KAAK,EAAE;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqC/B;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;QAC9C,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqC/B,8CAA8C;IACxC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CAU1D"}

package/dist/lib/db/key-lifecycle.js

@@ -0,0 +1,182 @@
+// Path: src/lib/db/key-lifecycle.ts
+//
+// CLI-side access to the durable key-lifecycle state (zn-vault migration 093).
+//
+// WHY THE CEREMONY WRITES HERE AND NOT TO A LOG FILE. The owner's requirement
+// was that a ceremony leave a record of who ran it, when, and how far it got —
+// the thing a shell script cannot give you, because a script that dies leaves
+// nothing and a script that is edited leaves no trace of the edit.
+//
+// `key_lifecycle_operations` gives all three, and two more that matter:
+//
+//   EXCLUSION IS IN THE DATABASE. A partial unique index means a second
+//   ceremony — or a ceremony during an LMK rotation — is refused by PostgreSQL,
+//   not by an `if` that both processes evaluate to false at the same instant.
+//
+//   THE HISTORY CANNOT BE REWRITTEN. `key_lifecycle_phase_events` is
+//   append-only by trigger and is written in the SAME transaction as the state
+//   change, so a ceremony that dies at phase 5 still shows how it reached
+//   phase 5.
+//
+// PORT NOTICE. The server has a richer repository for these tables
+// (`zn-vault/src/db/repo.key-lifecycle.ts`) with compare-and-swap on `epoch`.
+// This package ships to npm on its own and cannot import it. The contract is
+// the SCHEMA, pinned by the migration — not this file and not that one. What is
+// duplicated here is deliberately the minimum: claim, advance, finish, read.
+import { BaseDBClient } from './client.js';
+const COLUMNS = `operation_id, kind, state, phase, epoch, owner_node_id,
+  owner_principal, min_release, started_at, finished_at, last_error`;
+const PG_UNIQUE_VIOLATION = '23505';
+function toOperation(r) {
+    return {
+        operationId: r.operation_id,
+        kind: r.kind,
+        state: r.state,
+        phase: r.phase,
+        // BIGINT arrives as a string from some drivers, a number from others.
+        epoch: Number(r.epoch),
+        ownerNodeId: r.owner_node_id,
+        ownerPrincipal: r.owner_principal,
+        minRelease: r.min_release,
+        startedAt: r.started_at,
+        finishedAt: r.finished_at,
+        lastError: r.last_error,
+    };
+}
+export class KeyLifecycleOperations extends BaseDBClient {
+    /**
+     * Is the schema present?
+     *
+     * The CLI ships independently of the server, so it can meet a deployment that
+     * predates migration 093. Saying so plainly beats a `relation does not exist`
+     * in the middle of a ceremony.
+     */
+    async schemaPresent() {
+        await this.connect();
+        const r = await this.getRawClient().query(`SELECT to_regclass('public.key_lifecycle_operations')::text AS present`);
+        return (r.rows[0]?.present ?? null) !== null;
+    }
+    /** The operation currently holding the exclusion slot, if any. */
+    async active() {
+        await this.connect();
+        const r = await this.getRawClient().query(`SELECT ${COLUMNS} FROM key_lifecycle_operations WHERE state = 'IN_PROGRESS' LIMIT 1`);
+        const row = r.rows.at(0);
+        return row === undefined ? null : toOperation(row);
+    }
+    /**
+     * Start a ceremony, or find out who already holds the slot.
+     *
+     * Does NOT look before it leaps: a "is anything running?" SELECT followed by
+     * an INSERT is exactly the race the index exists to close. The INSERT is the
+     * check, and 23505 is the answer.
+     */
+    async claim(input) {
+        await this.connect();
+        const c = this.getRawClient();
+        try {
+            await c.query('BEGIN');
+            const r = await c.query(`INSERT INTO key_lifecycle_operations
+           (kind, state, phase, epoch, owner_node_id, owner_principal, min_release)
+         VALUES ('ESCROW_SNAPSHOT', 'IN_PROGRESS', $1, 0, $2, $3, $4)
+         RETURNING ${COLUMNS}`, [input.phase, input.ownerNodeId, input.ownerPrincipal, input.minRelease]);
+            const row = r.rows.at(0);
+            if (row === undefined)
+                throw new Error('claim: INSERT ... RETURNING produced no row');
+            // Same transaction: an operation whose history starts one commit late is
+            // an operation whose first phase can vanish.
+            await c.query(`INSERT INTO key_lifecycle_phase_events
+           (operation_id, seq, phase, state, node_id, detail)
+         VALUES ($1, 0, $2, 'IN_PROGRESS', $3, $4)`, [row.operation_id, input.phase, input.ownerNodeId,
+                input.detail ? JSON.stringify(input.detail) : null]);
+            await c.query('COMMIT');
+            return { ok: true, operation: toOperation(row) };
+        }
+        catch (error) {
+            await c.query('ROLLBACK').catch(() => undefined);
+            if (error.code !== PG_UNIQUE_VIOLATION)
+                throw error;
+            return { ok: false, active: await this.active() };
+        }
+    }
+    /**
+     * Move to the next phase, recording it in the same transaction.
+     *
+     * Compare-and-swap on `epoch`: a caller holding a stale read is refused
+     * rather than silently overwriting whoever moved first.
+     */
+    async advance(input) {
+        await this.connect();
+        const c = this.getRawClient();
+        const next = input.expectedEpoch + 1;
+        try {
+            await c.query('BEGIN');
+            const r = await c.query(`UPDATE key_lifecycle_operations
+            SET phase = $1, epoch = $2, updated_at = now()
+          WHERE operation_id = $3 AND epoch = $4 AND state = 'IN_PROGRESS'
+        RETURNING ${COLUMNS}`, [input.phase, next, input.operationId, input.expectedEpoch]);
+            const row = r.rows.at(0);
+            if (row === undefined) {
+                await c.query('ROLLBACK');
+                throw new Error(`Could not advance operation ${input.operationId} to '${input.phase}': it is ` +
+                    'no longer IN_PROGRESS at the expected epoch. Someone or something else ' +
+                    "moved it. Run 'ceremony status' before deciding what to do.");
+            }
+            await c.query(`INSERT INTO key_lifecycle_phase_events
+           (operation_id, seq, phase, state, node_id, detail)
+         VALUES ($1, $2, $3, 'IN_PROGRESS', $4, $5)`, [input.operationId, next, input.phase, input.nodeId,
+                input.detail ? JSON.stringify(input.detail) : null]);
+            await c.query('COMMIT');
+            return toOperation(row);
+        }
+        catch (error) {
+            await c.query('ROLLBACK').catch(() => undefined);
+            throw error;
+        }
+    }
+    /**
+     * Close the operation, releasing the slot.
+     *
+     * `ABANDONED` is a real transition with a reason rather than a DELETE: why a
+     * ceremony was abandoned is exactly what the next person needs to read, and a
+     * global exclusion with no escape hatch is a deadlock waiting for its first
+     * interrupted ceremony.
+     */
+    async finish(input) {
+        await this.connect();
+        const c = this.getRawClient();
+        const next = input.expectedEpoch + 1;
+        try {
+            await c.query('BEGIN');
+            const r = await c.query(`UPDATE key_lifecycle_operations
+            SET state = $1, epoch = $2, last_error = COALESCE($3, last_error),
+                updated_at = now(), finished_at = now()
+          WHERE operation_id = $4 AND epoch = $5 AND state = 'IN_PROGRESS'
+        RETURNING ${COLUMNS}`, [input.outcome, next, input.error ?? null, input.operationId, input.expectedEpoch]);
+            const row = r.rows.at(0);
+            if (row === undefined) {
+                await c.query('ROLLBACK');
+                throw new Error(`Could not close operation ${input.operationId}: it is no longer IN_PROGRESS ` +
+                    'at the expected epoch.');
+            }
+            await c.query(`INSERT INTO key_lifecycle_phase_events
+           (operation_id, seq, phase, state, node_id, detail)
+         VALUES ($1, $2, $3, $4, $5, $6)`, [input.operationId, next, row.phase, input.outcome, input.nodeId,
+                input.detail ? JSON.stringify(input.detail) : null]);
+            await c.query('COMMIT');
+            return toOperation(row);
+        }
+        catch (error) {
+            await c.query('ROLLBACK').catch(() => undefined);
+            throw error;
+        }
+    }
+    /** The full route travelled, oldest first. */
+    async history(operationId) {
+        await this.connect();
+        const r = await this.getRawClient().query(`SELECT seq, phase, state, at::text AS at, detail
+         FROM key_lifecycle_phase_events
+        WHERE operation_id = $1 ORDER BY seq ASC`, [operationId]);
+        return r.rows;
+    }
+}
+//# sourceMappingURL=key-lifecycle.js.map

package/dist/lib/db/key-lifecycle.js.map

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

package/dist/lib/db/lmk-escrow.d.ts

@@ -37,6 +37,13 @@ export interface LmkEscrowActiveRotation {
     status: string;
     startedAt: Date | null;
 }
+export interface RootKeyEnvelopeRow {
+    providerId: string;
+    providerType: string;
+    keyId: string | null;
+    ciphertext: Buffer;
+    kcv: string;
+}
 export interface LmkEscrowDatabaseSnapshot {
     capturedAt: Date;
     databaseName: string;
@@ -54,6 +61,17 @@ export interface LmkEscrowDatabaseSnapshot {
  * This class never unwraps LMKs and never writes to PostgreSQL.
  */
 export declare class LmkEscrowOperations extends BaseDBClient {
+    /**
+     * Read one root-key envelope, for sourcing the BSK from the hardware root
+     * instead of a cleartext file.
+     *
+     * `kcv` is the load-bearing column: it is what the returned key is checked
+     * against, and the appliance neither supplies it nor can influence it at read
+     * time. See `resolveBskFromProvider`.
+     */
+    getRootKeyEnvelope(providerId: string): Promise<RootKeyEnvelopeRow | null>;
+    /** Provider ids that have an envelope, for a useful "did you mean" on error. */
+    listRootKeyEnvelopeProviders(): Promise<string[]>;
     capture(backupId?: string): Promise<LmkEscrowDatabaseSnapshot>;
 }
 //# sourceMappingURL=lmk-escrow.d.ts.map

package/dist/lib/db/lmk-escrow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lmk-escrow.d.ts","sourceRoot":"","sources":["../../../src/lib/db/lmk-escrow.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,IAAI,CAAC;IAClB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,IAAI,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACrC,cAAc,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC/C,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACvC;AAqBD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IAC7C,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;CAqHrE"}
+{"version":3,"file":"lmk-escrow.d.ts","sourceRoot":"","sources":["../../../src/lib/db/lmk-escrow.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,IAAI,CAAC;IAClB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,IAAI,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACrC,cAAc,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC/C,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACvC;AAqBD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD;;;;;;;OAOG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAehF,gFAAgF;IAC1E,4BAA4B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQjD,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;CAqHrE"}

package/dist/lib/db/lmk-escrow.js

@@ -5,6 +5,31 @@ import { BaseDBClient } from './client.js';
  * This class never unwraps LMKs and never writes to PostgreSQL.
  */
 export class LmkEscrowOperations extends BaseDBClient {
+    /**
+     * Read one root-key envelope, for sourcing the BSK from the hardware root
+     * instead of a cleartext file.
+     *
+     * `kcv` is the load-bearing column: it is what the returned key is checked
+     * against, and the appliance neither supplies it nor can influence it at read
+     * time. See `resolveBskFromProvider`.
+     */
+    async getRootKeyEnvelope(providerId) {
+        await this.connect();
+        const result = await this.getRawClient().query(`SELECT provider_id AS "providerId",
+              provider_type AS "providerType",
+              key_id AS "keyId",
+              ciphertext,
+              kcv
+         FROM root_key_envelopes
+        WHERE provider_id = $1`, [providerId]);
+        return result.rows[0] ?? null;
+    }
+    /** Provider ids that have an envelope, for a useful "did you mean" on error. */
+    async listRootKeyEnvelopeProviders() {
+        await this.connect();
+        const result = await this.getRawClient().query(`SELECT provider_id AS "providerId" FROM root_key_envelopes ORDER BY provider_id`);
+        return result.rows.map((r) => r.providerId);
+    }
     async capture(backupId) {
         await this.connect();
         const client = this.getRawClient();

package/dist/lib/db/lmk-escrow.js.map

@@ -1 +1 @@
-{"version":3,"file":"lmk-escrow.js","sourceRoot":"","sources":["../../../src/lib/db/lmk-escrow.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA4E3C;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD,KAAK,CAAC,OAAO,CAAC,QAAiB;QAC7B,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACnC,MAAM,MAAM,CAAC,KAAK,CAAC,6DAA6D,CAAC,CAAC;QAElF,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,KAAK,CAAsB;;;;;;;;OAQ9D,CAAC,CAAC;YACH,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAExC,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,KAAK,CAAsB;;;;;;;;;;;;;;;;;;OAkB9D,CAAC,CAAC;YAEH,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,KAAK,CAAqB;;;;;;;;;;;OAW1D,CAAC,CAAC;YAEH,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,KAAK,CAA0B;;;;;;;;;;;OAWlE,CAAC,CAAC;YAEH,IAAI,MAAM,GAAkC,IAAI,CAAC;YACjD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,KAAK,CAAqB;;;;;;;;;;;;SAY3D,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACf,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACnC,MAAM,IAAI,KAAK,CAAC,UAAU,QAAQ,oCAAoC,CAAC,CAAC;gBAC1E,CAAC;gBACD,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACvC,IACE,SAAS,CAAC,MAAM,KAAK,UAAU;oBAC/B,CAAC,SAAS,CAAC,SAAS;oBACpB,SAAS,CAAC,QAAQ,KAAK,IAAI;oBAC3B,SAAS,CAAC,QAAQ,KAAK,EAAE;oBACzB,SAAS,CAAC,WAAW,KAAK,IAAI;oBAC9B,SAAS,CAAC,UAAU,KAAK,IAAI,EAC7B,CAAC;oBACD,MAAM,IAAI,KAAK,CAAC,UAAU,QAAQ,kDAAkD,CAAC,CAAC;gBACxF,CAAC;gBACD,MAAM,GAAG;oBACP,GAAG,SAAS;oBACZ,QAAQ,EAAE,SAAS,CAAC,QAAQ;oBAC5B,SAAS,EAAE,IAAI;oBACf,WAAW,EAAE,SAAS,CAAC,WAAW;oBAClC,UAAU,EAAE,SAAS,CAAC,UAAU;iBACjC,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO;gBACL,GAAG,QAAQ;gBACX,QAAQ,EAAE,cAAc,CAAC,IAAI;gBAC7B,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;gBACtC,cAAc,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;gBAC9C,MAAM;aACP,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"lmk-escrow.js","sourceRoot":"","sources":["../../../src/lib/db/lmk-escrow.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAoF3C;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD;;;;;;;OAOG;IACH,KAAK,CAAC,kBAAkB,CAAC,UAAkB;QACzC,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAC5C;;;;;;+BAMyB,EACzB,CAAC,UAAU,CAAC,CACb,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAChC,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,4BAA4B;QAChC,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAC5C,iFAAiF,CAClF,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,QAAiB;QAC7B,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACnC,MAAM,MAAM,CAAC,KAAK,CAAC,6DAA6D,CAAC,CAAC;QAElF,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,KAAK,CAAsB;;;;;;;;OAQ9D,CAAC,CAAC;YACH,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAExC,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,KAAK,CAAsB;;;;;;;;;;;;;;;;;;OAkB9D,CAAC,CAAC;YAEH,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,KAAK,CAAqB;;;;;;;;;;;OAW1D,CAAC,CAAC;YAEH,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,KAAK,CAA0B;;;;;;;;;;;OAWlE,CAAC,CAAC;YAEH,IAAI,MAAM,GAAkC,IAAI,CAAC;YACjD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,KAAK,CAAqB;;;;;;;;;;;;SAY3D,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACf,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACnC,MAAM,IAAI,KAAK,CAAC,UAAU,QAAQ,oCAAoC,CAAC,CAAC;gBAC1E,CAAC;gBACD,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACvC,IACE,SAAS,CAAC,MAAM,KAAK,UAAU;oBAC/B,CAAC,SAAS,CAAC,SAAS;oBACpB,SAAS,CAAC,QAAQ,KAAK,IAAI;oBAC3B,SAAS,CAAC,QAAQ,KAAK,EAAE;oBACzB,SAAS,CAAC,WAAW,KAAK,IAAI;oBAC9B,SAAS,CAAC,UAAU,KAAK,IAAI,EAC7B,CAAC;oBACD,MAAM,IAAI,KAAK,CAAC,UAAU,QAAQ,kDAAkD,CAAC,CAAC;gBACxF,CAAC;gBACD,MAAM,GAAG;oBACP,GAAG,SAAS;oBACZ,QAAQ,EAAE,SAAS,CAAC,QAAQ;oBAC5B,SAAS,EAAE,IAAI;oBACf,WAAW,EAAE,SAAS,CAAC,WAAW;oBAClC,UAAU,EAAE,SAAS,CAAC,UAAU;iBACjC,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO;gBACL,GAAG,QAAQ;gBACX,QAAQ,EAAE,cAAc,CAAC,IAAI;gBAC7B,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;gBACtC,cAAc,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;gBAC9C,MAAM;aACP,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/lib/db/preflight.d.ts

@@ -0,0 +1,42 @@
+import { BaseDBClient } from './client.js';
+import type { PreflightAuditHead, PreflightBackup, PreflightEnvelope, PreflightLmkVersion, PreflightRotation } from '../preflight.js';
+export interface PreflightDatabaseSnapshot {
+    capturedAt: Date;
+    databaseName: string;
+    postgresVersion: string;
+    walLsn: string;
+    transactionSnapshot: string;
+    latestMigration: string | null;
+    lmkVersions: PreflightLmkVersion[];
+    rootKeyEnvelopes: PreflightEnvelope[];
+    rootKeyEnvelopesTablePresent: boolean;
+    activeRotations: PreflightRotation[];
+    auditHead: PreflightAuditHead | null;
+    latestVerifiedBackup: PreflightBackup | null;
+}
+/**
+ * Capture the key-hierarchy state a BSK rotation depends on.
+ *
+ * READ ONLY, AND SAID SO TO POSTGRESQL. The transaction is opened
+ * `REPEATABLE READ READ ONLY`, which makes any write on this connection fail
+ * with SQLSTATE 25006 rather than relying on nobody having added one. Test 1.1
+ * of the milestone is "preflight over production, and ZERO writes"; a promise
+ * kept only by inspection is not evidence.
+ *
+ * WHY NOT THE API. `/v1/superadmin/rootkey/status` and `.../verify` each WRITE
+ * AN AUDIT ROW. Reading the state through them would break the zero-writes
+ * property invisibly — the preflight would be the thing that falsified its own
+ * result. This reads PostgreSQL directly, exactly as the escrow snapshot does.
+ *
+ * REPEATABLE READ, not READ COMMITTED: every query below must see one instant.
+ * A version list read before a rotation commits and an envelope list read after
+ * would produce an inventory that never existed, and the gates would be
+ * evaluated over that.
+ *
+ * Nothing here selects key material. `wrapped_lmk` is read as `octet_length`
+ * only, `root_key_envelopes.ciphertext` is not read at all.
+ */
+export declare class PreflightOperations extends BaseDBClient {
+    capture(): Promise<PreflightDatabaseSnapshot>;
+}
+//# sourceMappingURL=preflight.d.ts.map

package/dist/lib/db/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../../src/lib/db/preflight.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,IAAI,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,gBAAgB,EAAE,iBAAiB,EAAE,CAAC;IACtC,4BAA4B,EAAE,OAAO,CAAC;IACtC,eAAe,EAAE,iBAAiB,EAAE,CAAC;IACrC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACrC,oBAAoB,EAAE,eAAe,GAAG,IAAI,CAAC;CAC9C;AAgDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IAC7C,OAAO,IAAI,OAAO,CAAC,yBAAyB,CAAC;CAkJpD"}

package/dist/lib/db/preflight.js

@@ -0,0 +1,165 @@
+// Path: src/lib/db/preflight.ts
+import { BaseDBClient } from './client.js';
+/**
+ * Capture the key-hierarchy state a BSK rotation depends on.
+ *
+ * READ ONLY, AND SAID SO TO POSTGRESQL. The transaction is opened
+ * `REPEATABLE READ READ ONLY`, which makes any write on this connection fail
+ * with SQLSTATE 25006 rather than relying on nobody having added one. Test 1.1
+ * of the milestone is "preflight over production, and ZERO writes"; a promise
+ * kept only by inspection is not evidence.
+ *
+ * WHY NOT THE API. `/v1/superadmin/rootkey/status` and `.../verify` each WRITE
+ * AN AUDIT ROW. Reading the state through them would break the zero-writes
+ * property invisibly — the preflight would be the thing that falsified its own
+ * result. This reads PostgreSQL directly, exactly as the escrow snapshot does.
+ *
+ * REPEATABLE READ, not READ COMMITTED: every query below must see one instant.
+ * A version list read before a rotation commits and an envelope list read after
+ * would produce an inventory that never existed, and the gates would be
+ * evaluated over that.
+ *
+ * Nothing here selects key material. `wrapped_lmk` is read as `octet_length`
+ * only, `root_key_envelopes.ciphertext` is not read at all.
+ */
+export class PreflightOperations extends BaseDBClient {
+    async capture() {
+        await this.connect();
+        const client = this.getRawClient();
+        await client.query('BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
+        try {
+            const identityResult = await client.query(`
+        SELECT
+          clock_timestamp() AS "capturedAt",
+          current_database() AS "databaseName",
+          current_setting('server_version') AS "postgresVersion",
+          pg_current_wal_lsn()::text AS "walLsn",
+          txid_current_snapshot()::text AS "transactionSnapshot",
+          (SELECT name FROM _migrations ORDER BY name DESC LIMIT 1) AS "latestMigration",
+          to_regclass('public.root_key_envelopes')::text AS "rootKeyEnvelopesTable"
+      `);
+            // pg's types claim `rows[0]` is always present. It is not, and a
+            // preflight that reads `undefined.databaseName` reports a crash where it
+            // should report an unreadable database.
+            const identity = identityResult.rows.at(0);
+            if (identity === undefined) {
+                throw new Error('Could not read PostgreSQL snapshot identity');
+            }
+            // octet_length, never the bytes. A preflight that pulled wrapped key
+            // material into a CLI process would put it in a core dump, a swap file
+            // and an error report, for no gain: every gate here is about presence.
+            const versionsResult = await client.query(`
+        SELECT
+          version,
+          status::text AS status,
+          octet_length(wrapped_lmk) AS "wrappedBytes"
+        FROM lmk_versions
+        ORDER BY version
+      `);
+            const rootKeyEnvelopesTablePresent = identity.rootKeyEnvelopesTable !== null;
+            // A node predating migration 092 has no such table, and `to_regclass`
+            // answering NULL is the only safe way to ask — a failing query would
+            // abort the whole transaction, losing the reads already taken.
+            const envelopesResult = rootKeyEnvelopesTablePresent
+                ? await client.query(`
+            SELECT
+              provider_id AS "providerId",
+              provider_type AS "providerType",
+              key_id AS "keyId",
+              kcv
+            FROM root_key_envelopes
+            ORDER BY provider_id
+          `)
+                : { rows: [] };
+            const rotationResult = await client.query(`
+        SELECT
+          rotation_id AS "rotationId",
+          old_lmk_version AS "oldLmkVersion",
+          new_lmk_version AS "newLmkVersion",
+          status::text AS status,
+          started_at AS "startedAt"
+        FROM lmk_rotation_progress
+        WHERE status IN ('IN_PROGRESS', 'FAILED')
+        ORDER BY started_at DESC
+      `);
+            const auditResult = await client.query(`
+        SELECT
+          id::text AS id,
+          ts AS timestamp,
+          curr_hmac AS "currentHmac",
+          lmk_version AS "lmkVersion",
+          hmac_format_version AS "hmacFormatVersion"
+        FROM audit_log
+        WHERE curr_hmac IS NOT NULL
+        ORDER BY id DESC
+        LIMIT 1
+      `);
+            const backupResult = await client.query(`
+        SELECT
+          id,
+          filename,
+          completed_at AS "completedAt",
+          verified_at AS "verifiedAt"
+        FROM backups
+        WHERE deleted_at IS NULL
+          AND status::text = 'VERIFIED'
+          AND encrypted = true
+          AND verified_at IS NOT NULL
+          AND completed_at IS NOT NULL
+        ORDER BY verified_at DESC
+        LIMIT 1
+      `);
+            await client.query('COMMIT');
+            const auditHeadRow = auditResult.rows.at(0);
+            const backupRow = backupResult.rows.at(0);
+            return {
+                capturedAt: identity.capturedAt,
+                databaseName: identity.databaseName,
+                postgresVersion: identity.postgresVersion,
+                walLsn: identity.walLsn,
+                transactionSnapshot: identity.transactionSnapshot,
+                latestMigration: identity.latestMigration,
+                lmkVersions: versionsResult.rows.map((row) => {
+                    const bytes = row.wrappedBytes === null ? 0 : Number(row.wrappedBytes);
+                    return {
+                        version: row.version,
+                        status: row.status,
+                        hasWrappedLmk: bytes > 0,
+                        wrappedBytes: bytes,
+                    };
+                }),
+                rootKeyEnvelopes: envelopesResult.rows,
+                rootKeyEnvelopesTablePresent,
+                activeRotations: rotationResult.rows.map((row) => ({
+                    rotationId: row.rotationId,
+                    oldLmkVersion: row.oldLmkVersion,
+                    newLmkVersion: row.newLmkVersion,
+                    status: row.status,
+                    startedAt: row.startedAt?.toISOString() ?? null,
+                })),
+                auditHead: auditHeadRow !== undefined
+                    ? {
+                        id: auditHeadRow.id,
+                        timestamp: auditHeadRow.timestamp?.toISOString() ?? null,
+                        currentHmacBase64: Buffer.from(auditHeadRow.currentHmac).toString('base64'),
+                        lmkVersion: auditHeadRow.lmkVersion,
+                        hmacFormatVersion: auditHeadRow.hmacFormatVersion,
+                    }
+                    : null,
+                latestVerifiedBackup: backupRow !== undefined
+                    ? {
+                        id: backupRow.id,
+                        filename: backupRow.filename,
+                        completedAt: backupRow.completedAt.toISOString(),
+                        verifiedAt: backupRow.verifiedAt.toISOString(),
+                    }
+                    : null,
+            };
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=preflight.js.map

package/dist/lib/db/preflight.js.map

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

package/dist/lib/kcv.d.ts

@@ -0,0 +1,34 @@
+/** Domain-separation label. Versioned; changing it is a new KCV format. */
+export declare const BSK_KCV_CONTEXT = "zn-vault-bsk-kcv-v1";
+/**
+ * Compute the publishable Key Check Value of a bootstrap key.
+ *
+ * Deterministic: same key, same KCV — across providers, nodes and sites.
+ * Safe to log and display; never reveals or accelerates recovery of the key.
+ *
+ * @throws if the key is not exactly 32 bytes. A short buffer would still
+ *   produce a well-formed fingerprint — of the wrong thing — and the escrow
+ *   gate would report it as "the two custodies hold different keys".
+ */
+export declare function computeBskKcv(key: Buffer): string;
+/**
+ * Is this string a KCV of the construction above?
+ *
+ * On this side of the port the values being gated arrive from PostgreSQL
+ * (`root_key_envelopes.kcv`, a TEXT column with no CHECK constraint) and from
+ * an unauthenticated `/v1/health` body. They are not merely compared: they are
+ * republished into signed preflight evidence that leaves the CPD. A
+ * "looks-plausible" check would let arbitrary text — including something
+ * shaped like key material — into that artefact.
+ *
+ * Pinning the ACTUAL construction closes it for free: anything a KCV
+ * comparison could ever legitimately succeed against matches this pattern, so
+ * refusing everything else costs nothing. A malformed value is a protocol
+ * violation, distinct from — and checked before — a well-formed KCV that
+ * disagrees.
+ *
+ * Non-strings return false rather than throwing: the caller is reading a
+ * nullable column.
+ */
+export declare function isBskKcv(value: string): boolean;
+//# sourceMappingURL=kcv.d.ts.map

package/dist/lib/kcv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kcv.d.ts","sourceRoot":"","sources":["../../src/lib/kcv.ts"],"names":[],"mappings":"AAuCA,2EAA2E;AAC3E,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAKrD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQjD;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG/C"}