@coffre/vault 0.1.1 → 0.1.3

package/README.md

@@ -10,9 +10,8 @@ import { postgres, vault } from '@coffre/vault/cloudflare';
 
 export default vault((env) => ({
   database: postgres(env.VAULT_HYPERDRIVE), // coffre_vault_runtime, caching disabled
-  kek: { id: env.KEK_ID, key: env.KEK }, // or awsKms({ keyArn, credentials })
+  kek: { id: env.VAULT_KEY_ID, key: env.VAULT_KEY }, // or awsKms({ keyArn, credentials }), with a signingKey
   rootAdmins: env.ROOT_ADMINS.split(','),
-  signingKey: env.SIGNING_KEY,
 }));
 ```
 

package/dist/cloudflare.d.ts

@@ -1,4 +1,4 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-qXbB_vlp.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-DPxyTJNN.js";
 import { AdmitInput, RemoveInput, RewrapInput, SetAccessInput, UnwrapInput, Vault, VerifyLogInput, WrapInput } from "@coffre/core/vault";
 import { PostgresDatabase, PostgresDatabase as PostgresDatabase$1, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";
@@ -42,7 +42,7 @@ export declare class VaultEntrypoint extends WorkerEntrypoint implements Vault {
     checkpoint: import("@coffre/core/vault").Checkpoint;
   }>>;
   about(): Promise<{
-    publicKey: string;
+    checkpointKeys: Record<string, import("@coffre/core/vault").CheckpointKey>;
     rootAdmins: string[];
   }>;
   verifyLog(input: VerifyLogInput): Promise<import("@coffre/core/vault").LogVerification>;
@@ -52,4 +52,4 @@ export declare class VaultEntrypoint extends WorkerEntrypoint implements Vault {
 /** The vault Worker's default export, `VaultEntrypoint`, configured from its `env`. */
 export declare function vault<Env>(configure_: (env: Env) => WorkersVaultConfig): typeof VaultEntrypoint;
 //#endregion
-export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type PostgresDatabase, type SecretContext, type Vault, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, postgres, verifyCheckpoint };
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type PostgresDatabase, type SecretContext, type Vault, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, postgres, verifyCheckpoint };

package/dist/cloudflare.js

@@ -1,5 +1,5 @@
-import { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, verifyCheckpoint } from "./index.js";
-import { n as prepareVault, r as resolveVaultConfig, t as openVault } from "./vault-DvTsSAOX.js";
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-DHuqw-IB.js";
+import { n as prepareVault, t as openVault } from "./vault-pexzy7Z-.js";
 import { createDatabase } from "@coffre/db";
 import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";
@@ -70,4 +70,4 @@ function vault(configure_) {
 	return VaultEntrypoint;
 }
 //#endregion
-export { KekBadClaimError, KekUnavailableError, VaultEntrypoint, awsKms, checkpointMessage, postgres, vault, verifyCheckpoint };
+export { KekBadClaimError, KekUnavailableError, VaultEntrypoint, awsKms, checkpointMessage, derivedSigningKey, postgres, vault, verifyCheckpoint };

package/dist/{index-qXbB_vlp.d.ts → index-DPxyTJNN.d.ts}

@@ -16,25 +16,35 @@ type Kek = {
  *
  *   {
  *     kek: awsKms({ keyArn: env.KMS_KEY_ARN, credentials: { … } }),
- *     previousKeks: [{ id: 'kek-2025-01', key: env.KEK_2025_01 }],
+ *     previousKeks: [{ id: 'vault-2025-01-10-k7q2xm', key: env.OLD_VAULT_KEY }],
  *     rootAdmins: ['admin@acme.example'],
- *     signingKey: env.SIGNING_KEY,
+ *     signingKey: env.SIGNING_KEY, // required with a key service; derived from a local KEK otherwise
  *   }
  */
 type VaultConfig = {
   /** Wraps every new data key. */
   kek: Kek;
-  /** Older KEKs, still unwrapping what they wrapped until a rewrap moves it on. */
+  /**
+   * Older KEKs, still unwrapping what they wrapped until a rewrap moves it
+   * on, and verifying what the vault wrote under them before the rotation.
+   */
   previousKeks?: readonly Kek[];
   /** At least one email: the only way into a fresh instance, and the only members nobody can remove. */
   rootAdmins: readonly string[];
-  /** 32 random bytes, base64: the Ed25519 seed audit checkpoints are signed with. */
-  signingKey: string;
+  /**
+   * 32 random bytes, base64: the seed of the vault's own keys, which MAC its
+   * log entries, seal member rows and sign checkpoints. Leave it out with a
+   * local KEK, and the vault derives it from the KEK. Required when a key
+   * service holds the KEK, as AWS KMS does: the vault never sees that key.
+   */
+  signingKey?: string;
   /** At most `count` data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
   bulkLimit?: {
     count: number;
     windowMinutes: number;
   };
 };
+/** The signing key a local KEK stands for, when the vault is given none: HKDF-SHA-256 of the KEK. */
+declare function derivedSigningKey(kek: Uint8Array): Buffer;
 //#endregion
-export { KekUnavailableError$1 as a, awsKms as c, Kek as d, VaultConfig as f, KekProvider$1 as i, checkpointMessage$1 as l, AwsKmsOptions as n, SecretContext as o, KekBadClaimError$1 as r, WrappedDek as s, AwsCredentials as t, verifyCheckpoint$1 as u };
+export { KekUnavailableError$1 as a, awsKms as c, Kek as d, VaultConfig as f, KekProvider$1 as i, checkpointMessage$1 as l, AwsKmsOptions as n, SecretContext as o, derivedSigningKey as p, KekBadClaimError$1 as r, WrappedDek as s, AwsCredentials as t, verifyCheckpoint$1 as u };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-qXbB_vlp.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-DPxyTJNN.js";
 export type * from "@coffre/core/vault";
-export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type SecretContext, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, verifyCheckpoint };
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type SecretContext, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/index.js

@@ -1,3 +1,2 @@
-import { checkpointMessage, verifyCheckpoint } from "@coffre/core/vault";
-import { KekBadClaimError, KekUnavailableError, awsKms } from "@coffre/core/kek";
-export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, verifyCheckpoint };
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, t as KekBadClaimError } from "./src-DHuqw-IB.js";
+export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-qXbB_vlp.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-DPxyTJNN.js";
 import { Vault, Vault as Vault$1 } from "@coffre/core/vault";
 import { Database } from "@coffre/db";
 import "@coffre/core/audit";
@@ -45,4 +45,4 @@ export declare function serveVault(config: NodeVaultConfig & {
 /** The vault that `serveVault` runs, from the server's side of its socket. */
 export declare function connectVault(socket: string): Vault;
 //#endregion
-export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type LocalVault, type SecretContext, type Vault, type VaultConfig, type VaultOptions, type WrappedDek, awsKms, checkpointMessage, verifyCheckpoint };
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type LocalVault, type SecretContext, type Vault, type VaultConfig, type VaultOptions, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/node.js

@@ -1,5 +1,5 @@
-import { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, verifyCheckpoint } from "./index.js";
-import { n as prepareVault, r as resolveVaultConfig, t as openVault } from "./vault-DvTsSAOX.js";
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-DHuqw-IB.js";
+import { n as prepareVault, t as openVault } from "./vault-pexzy7Z-.js";
 import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
 import { Agent, createServer, request } from "node:http";
 import { openDatabase } from "@coffre/db/connect";
@@ -139,4 +139,4 @@ async function readBody(stream) {
 	return Buffer.concat(chunks).toString("utf8");
 }
 //#endregion
-export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, connectVault, localVault, serveVault, verifyCheckpoint };
+export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, connectVault, derivedSigningKey, localVault, serveVault, verifyCheckpoint };

package/dist/src-DHuqw-IB.js

@@ -0,0 +1,113 @@
+import { checkpointMessage as checkpointMessage$1, verifyCheckpoint as verifyCheckpoint$1 } from "@coffre/core/vault";
+import { KekBadClaimError as KekBadClaimError$1, KekRegistry, KekUnavailableError as KekUnavailableError$1, LocalKekProvider, awsKms } from "@coffre/core/kek";
+import { hkdfSync } from "node:crypto";
+//#region src/config.ts
+/**
+* 1000 keys in 15 minutes: twenty `coffre run`s of a 50-key environment
+* back to back, which no person or deploy pipeline does, while a script
+* pulling every secret it can reach stops within a few seconds.
+*/
+const DEFAULT_BULK_LIMIT = {
+	count: 1e3,
+	windowMs: 9e5
+};
+function key32(value, what) {
+	const raw = Buffer.from(value, "base64");
+	if (raw.length !== 32) throw new Error(`${what} must be 32 bytes, base64; got ${raw.length} bytes`);
+	return raw;
+}
+const KEK_ID = /^[A-Za-z0-9._-]{1,64}$/;
+const KEK_PROVIDER = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** Every row records it, and `provider:keyId` finds the KEK again: visible ASCII, bounded. */
+const KEK_NAME = /^[\x21-\x7e]{1,255}$/;
+/** The label no other use of a KEK shares: a local KEK is otherwise only ever an AES-256-GCM key. */
+const SIGNING_KEY_LABEL = "coffre.vault.signing-key.v1";
+/** The signing key a local KEK stands for, when the vault is given none: HKDF-SHA-256 of the KEK. */
+function derivedSigningKey(kek) {
+	return Buffer.from(hkdfSync("sha256", kek, /* @__PURE__ */ new Uint8Array(0), SIGNING_KEY_LABEL, 32));
+}
+/** A KEK as the registry takes it, and the signing key it stands for when it is one the vault holds. */
+function kek(entry) {
+	if (!("wrap" in entry)) {
+		const { id, key } = entry;
+		if (!KEK_ID.test(id)) throw new Error(`the vault key's ID "${id}" (kek.id) must be 1-64 letters, digits, dots, dashes or underscores`);
+		const raw = key32(key, `the vault key ${id}`);
+		return {
+			provider: new LocalKekProvider(raw, id),
+			signingKey: derivedSigningKey(raw)
+		};
+	}
+	const { provider, keyId, keyVersion } = entry;
+	if (typeof provider !== "string" || !KEK_PROVIDER.test(provider)) throw new Error(`a key service's name (kek.provider) must be 1-32 lowercase letters, digits or dashes; got "${String(provider)}"`);
+	if (typeof keyId !== "string" || !KEK_NAME.test(keyId) || typeof keyVersion !== "string" || !KEK_NAME.test(keyVersion)) throw new Error(`vault key ${provider}: keyId and keyVersion must be 1-255 visible ASCII characters`);
+	if (typeof entry.wrap !== "function" || typeof entry.unwrap !== "function") throw new Error(`vault key ${provider}:${keyId} needs wrap() and unwrap()`);
+	return {
+		provider: entry,
+		signingKey: null
+	};
+}
+/** Check a deployment's vault configuration, failing on the first problem. */
+function resolveVaultConfig(config) {
+	const keks = [config.kek, ...config.previousKeks ?? []].map(kek);
+	const [current, ...previous] = keks.map((entry) => entry.provider);
+	const refs = [current, ...previous].map(({ provider, keyId }) => `${provider}:${keyId}`);
+	const twice = refs.find((ref, i) => refs.indexOf(ref) !== i);
+	if (twice !== void 0) throw new Error(`two vault keys share an id: ${twice}`);
+	return {
+		keks: new KekRegistry(current, previous),
+		rootAdmins: checkRootAdmins(config.rootAdmins),
+		signingKeys: signingKeys(config.signingKey, keks),
+		bulkLimit: config.bulkLimit === void 0 ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit)
+	};
+}
+/**
+* The key the vault signs with, then every other it verifies with. It signs
+* with `signingKey` when it is given one, and otherwise with the key the
+* primary KEK stands for. It verifies with the keys every local KEK stands
+* for too, the previous ones included: a KEK rotation changes the derived
+* signing key, and what the old one signed before the rotation must still
+* verify, for as long as the old KEK stays configured. Nothing after it does
+* (`#settle` in vault.ts).
+*/
+function signingKeys(given, keks) {
+	const derived = keks.flatMap((entry) => entry.signingKey === null ? [] : [entry.signingKey]);
+	let signing;
+	if (given !== void 0) signing = key32(given, "the signing key");
+	else if (keks[0].signingKey !== null) signing = keks[0].signingKey;
+	else {
+		const { provider, keyId } = keks[0].provider;
+		throw new Error(`signingKey is required with the ${provider} vault key ${keyId}: the vault derives its signing key only from a vault key it holds, and a key service never hands its key over. Set signingKey to 32 random bytes, base64 (openssl rand -base64 32), and keep it with the vault key.`);
+	}
+	return [signing, ...derived].filter((key, i, all) => all.findIndex((other) => other.equals(key)) === i);
+}
+function checkBulkLimit({ count, windowMinutes }) {
+	if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0)) throw new Error("bulkLimit needs a whole count of at least 1 and a window above 0 minutes");
+	return {
+		count,
+		windowMs: windowMinutes * 6e4
+	};
+}
+function isHumanEmail(value) {
+	if (value.length > 254) return false;
+	const parts = value.split("@");
+	if (parts.length !== 2) return false;
+	const [local, domain] = parts;
+	if (local.length === 0 || local.length > 64 || local.startsWith(".") || local.endsWith(".") || local.includes("..") || !/^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+$/.test(local)) return false;
+	const labels = domain.split(".");
+	if (labels.length < 2) return false;
+	return labels.every((label) => label.length > 0 && label.length <= 63 && /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/.test(label));
+}
+/**
+* Root admins, lowercased the way they are compared. At least one, in every
+* mode: they are the only way into a fresh instance, and the only members
+* nobody can remove.
+*/
+function checkRootAdmins(emails) {
+	const rootAdmins = [...new Set(emails.map((entry) => entry.trim()).filter((entry) => entry.length > 0))];
+	if (rootAdmins.length === 0) throw new Error("rootAdmins must name at least one email, or nobody can manage coffre");
+	const invalid = rootAdmins.find((entry) => !isHumanEmail(entry));
+	if (invalid) throw new Error(`rootAdmins must be human email identities; invalid: ${invalid}`);
+	return rootAdmins.map((entry) => entry.toLowerCase());
+}
+//#endregion
+export { verifyCheckpoint$1 as a, checkpointMessage$1 as i, KekUnavailableError$1 as n, derivedSigningKey as o, awsKms as r, resolveVaultConfig as s, KekBadClaimError$1 as t };