@coffre/vault 0.1.2 → 0.1.4

package/README.md

@@ -10,7 +10,7 @@ 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 }), with a signingKey
+  kek: { id: env.VAULT_KEY_ID, key: env.VAULT_KEY }, // or awsKms({ keyArn, credentials }), with a signingKey
   rootAdmins: env.ROOT_ADMINS.split(','),
 }));
 ```

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, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CapZlhbz.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";

package/dist/cloudflare.js

@@ -1,12 +1,16 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-D1C9S6VS.js";
-import { n as prepareVault, t as openVault } from "./vault-D5ZahBN1.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-PQvFopA6.js";
 import { createDatabase } from "@coffre/db";
 import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";
 //#region src/cloudflare.ts
 /** Set when the Worker's module runs `vault(…)`, before any call comes in. */
 let configure = null;
-/** The configuration, checked and made ready once per `env`, which the isolate keeps. */
+/**
+* The configuration, checked and made ready once per `env`, which the
+* isolate keeps: the ready value itself, never the work of making it, which
+* would belong to the call that started it (vault.ts, `PreparedVault`).
+*/
 const ready = /* @__PURE__ */ new WeakMap();
 /**
 * What the app's `VAULT` service binding calls. Each call gets a database of
@@ -19,14 +23,14 @@ var VaultEntrypoint = class extends WorkerEntrypoint {
 		if (entry === void 0) {
 			if (configure === null) throw new Error("the vault Worker must export default vault(…)");
 			const config = configure(env);
-			entry = prepareVault(resolveVaultConfig(config)).then((prepared) => ({
+			const prepared = await prepareVault(resolveVaultConfig(config));
+			entry = ready.get(env) ?? {
 				database: config.database,
 				prepared
-			}));
+			};
 			ready.set(env, entry);
-			entry.catch(() => ready.delete(env));
 		}
-		const { database, prepared } = await entry;
+		const { database, prepared } = entry;
 		return openVault(createDatabase(new HyperdrivePool(database.hyperdrive.connectionString)), prepared);
 	}
 	async unwrap(input) {

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

@@ -16,7 +16,7 @@ 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, // required with a key service; derived from a local KEK otherwise
  *   }

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, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CapZlhbz.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, derivedSigningKey, verifyCheckpoint };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, t as KekBadClaimError } from "./src-D1C9S6VS.js";
+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, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CapZlhbz.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";

package/dist/node.js

@@ -1,5 +1,5 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-D1C9S6VS.js";
-import { n as prepareVault, t as openVault } from "./vault-D5ZahBN1.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-PQvFopA6.js";
 import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
 import { Agent, createServer, request } from "node:http";
 import { openDatabase } from "@coffre/db/connect";

package/dist/{src-D1C9S6VS.js → src-DHuqw-IB.js}

@@ -30,17 +30,17 @@ function derivedSigningKey(kek) {
 function kek(entry) {
 	if (!("wrap" in entry)) {
 		const { id, key } = entry;
-		if (!KEK_ID.test(id)) throw new Error(`KEK id "${id}" must be 1-64 letters, digits, dots, dashes or underscores`);
-		const raw = key32(key, `KEK ${id}`);
+		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 KEK provider's name 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(`KEK ${provider}: keyId and keyVersion must be 1-255 visible ASCII characters`);
-	if (typeof entry.wrap !== "function" || typeof entry.unwrap !== "function") throw new Error(`KEK ${provider}:${keyId} needs wrap() and unwrap()`);
+	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
@@ -52,7 +52,7 @@ function resolveVaultConfig(config) {
 	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 KEKs share an id: ${twice}`);
+	if (twice !== void 0) throw new Error(`two vault keys share an id: ${twice}`);
 	return {
 		keks: new KekRegistry(current, previous),
 		rootAdmins: checkRootAdmins(config.rootAdmins),
@@ -76,7 +76,7 @@ function signingKeys(given, keks) {
 	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} KEK ${keyId}: the vault derives its signing key only from a KEK 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 KEK.`);
+		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);
 }

package/dist/{vault-D5ZahBN1.js → vault-PQvFopA6.js}

@@ -377,7 +377,7 @@ function forward(entries, keys, current) {
 */
 function withCause(reason) {
 	if (!/^written under vault:\S+, a key this verifier does not hold$/.test(reason)) return reason;
-	return `${reason}: either it is forged, or the vault wrote it under another KEK or signing key, which must stay configured: a KEK that was replaced stays in previousKeks`;
+	return `${reason}: either it is forged, or the vault wrote it under another vault key or signing key, which must stay configured: a vault key that was replaced stays in the vault's config, in previousKeks`;
 }
 /**
 * Whether the log still holds `head` where it was: not rewritten, nor cut
@@ -792,8 +792,7 @@ async function prepareVault(config, options = {}) {
 		reported: /* @__PURE__ */ new Set(),
 		since: null,
 		superseded: null,
-		settling: null,
-		kekCheck: null,
+		kekChecked: false,
 		wrongKek: null
 	};
 }
@@ -890,7 +889,7 @@ const MESSAGES = {
 	root_admin: "root admins are set in the vault configuration",
 	invalid: "not something the rules allow",
 	log_broken: "the vault log does not hold from the last checkpoint",
-	wrong_kek: "this vault's KEK does not open the data it holds",
+	wrong_kek: "this vault's key does not open the data it holds",
 	tampered: "this member's record failed the vault's integrity check"
 };
 /**
@@ -1100,12 +1099,7 @@ var VaultService = class {
 	*/
 	async #settled() {
 		const prepared = this.#prepared;
-		if (prepared.since === null && prepared.superseded === null) {
-			prepared.settling ??= this.#settle().finally(() => {
-				prepared.settling = null;
-			});
-			await prepared.settling;
-		}
+		if (prepared.since === null && prepared.superseded === null) await this.#settle();
 		return prepared.superseded;
 	}
 	/**
@@ -1140,7 +1134,7 @@ var VaultService = class {
 				if (attempt < 3 && error instanceof Retry) continue;
 				throw error;
 			}
-			prepared.superseded = first === void 0 ? `the vault's entries are under ${newest.keyId}, a key this vault does not hold: it was given the wrong KEK or signing key, or a KEK it replaced is missing from previousKeks` : `the log moved on from this vault's key, ${current}, to ${newest.keyId}: a vault given a newer KEK replaced it, and a replaced key writes nothing more`;
+			prepared.superseded = first === void 0 ? `the vault's entries are under ${newest.keyId}, a key this vault does not hold: it was given the wrong vault key or signing key, or a vault key it replaced is missing from previousKeks in its config` : `the log moved on from this vault's key, ${current}, to ${newest.keyId}: a vault given a newer vault key replaced it, and a replaced key writes nothing more`;
 			return;
 		}
 	}
@@ -1189,7 +1183,7 @@ var VaultService = class {
 		return appendEntries(tx, prepared.logKey, entries, async (locked) => {
 			const rotation = await latestVaultEntry(locked, [KEY_ROTATE]);
 			if (rotation === void 0 || prepared.logKeys.some((key) => key.keyId === rotation.keyId)) return;
-			prepared.superseded = `the log moved on to ${rotation.keyId}, a key this vault does not hold: a vault given a newer KEK replaced it, and a replaced key writes nothing more`;
+			prepared.superseded = `the log moved on to ${rotation.keyId}, a key this vault does not hold: a vault given a newer vault key replaced it, and a replaced key writes nothing more`;
 			throw new Error(prepared.superseded);
 		});
 	}
@@ -1910,19 +1904,21 @@ var VaultService = class {
 	/**
 	* Null when every KEK the vault is given opens what it wrapped; otherwise
 	* why not, naming the KEK, never its key. Decided once per process, before
-	* its first key operation or checkpoint. A key service that cannot answer
-	* leaves it undecided: the error is thrown, and the next call asks again.
+	* its first key operation or checkpoint: until then, each call checks for
+	* itself, over its own database, and the first verdict is kept. A key
+	* service that cannot answer leaves it undecided: the error is thrown,
+	* and the next call asks again.
 	*/
-	#kekMismatch() {
+	async #kekMismatch() {
 		const prepared = this.#prepared;
-		if (prepared.kekCheck === null) {
-			const check = this.#checkKeks();
-			prepared.kekCheck = check;
-			check.then((wrong) => void (prepared.wrongKek = wrong), () => {
-				if (prepared.kekCheck === check) prepared.kekCheck = null;
-			});
+		if (!prepared.kekChecked) {
+			const wrong = await this.#checkKeks();
+			if (!prepared.kekChecked) {
+				prepared.wrongKek = wrong;
+				prepared.kekChecked = true;
+			}
 		}
-		return prepared.kekCheck;
+		return prepared.wrongKek;
 	}
 	/**
 	* Each KEK opens its check value, or, with none recorded yet (a fresh
@@ -1933,12 +1929,7 @@ var VaultService = class {
 	async #checkKeks() {
 		const superseded = await this.#settled();
 		if (superseded !== null) return superseded;
-		const checks = /* @__PURE__ */ new Map();
-		for (const entry of await vaultEntriesOf(this.#db, [KEY_CHECK], -1n, VERIFY_BATCH)) {
-			if (!this.#authentic(entry)) continue;
-			const wrapped = JSON.parse(entry.metadata);
-			checks.set(`${wrapped.kekProvider}:${wrapped.kekId}`, unwrappable(wrapped));
-		}
+		const checks = await this.#checkValues(this.#db);
 		const budget = this.#prepared.options.keyBudgetMs;
 		for (const kek of this.#config.keks.all) {
 			const operation = {
@@ -1956,7 +1947,7 @@ var VaultService = class {
 					throw error;
 				}
 			};
-			const mismatch = `this vault's ${kek.provider} KEK ${kek.keyId} does not open the data it holds: it is not the key that wrapped it`;
+			const mismatch = `the vault key ${kek.keyId}${kek.provider === "local" ? "" : ` (${kek.provider})`}, kek or previousKeks in the vault's config, is not the one that wrapped these values`;
 			const check = checks.get(`${kek.provider}:${kek.keyId}`);
 			if (check !== void 0) {
 				if (!await opens(check, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE)) return mismatch;
@@ -1977,18 +1968,32 @@ var VaultService = class {
 			}
 			if (samples.length > 0 && proof === null) return mismatch;
 			const wrapped = await kek.wrap(Buffer.from(KEY_CHECK_VALUE), KEY_CHECK_CONTEXT, operation);
-			await this.#db.transaction((tx) => this.#append(tx, [{
-				actor: VAULT_ACTOR,
-				action: KEY_CHECK,
-				decision: "allow",
-				metadata: JSON.stringify({
-					...serialisable(wrapped),
-					proof
-				})
-			}]));
+			await this.#db.transaction(async (tx) => {
+				await lockLogHead(tx);
+				if ((await this.#checkValues(tx)).has(`${kek.provider}:${kek.keyId}`)) return;
+				await this.#append(tx, [{
+					actor: VAULT_ACTOR,
+					action: KEY_CHECK,
+					decision: "allow",
+					metadata: JSON.stringify({
+						...serialisable(wrapped),
+						proof
+					})
+				}]);
+			});
 		}
 		return null;
 	}
+	/** Each KEK's recorded check value, by `provider:keyId`. */
+	async #checkValues(db) {
+		const checks = /* @__PURE__ */ new Map();
+		for (const entry of await vaultEntriesOf(db, [KEY_CHECK], -1n, VERIFY_BATCH)) {
+			if (!this.#authentic(entry)) continue;
+			const wrapped = JSON.parse(entry.metadata);
+			checks.set(`${wrapped.kekProvider}:${wrapped.kekId}`, unwrappable(wrapped));
+		}
+		return checks;
+	}
 	/** The last checkpoint the vault signed, and the entry that holds it: its newest allowed `audit.checkpoint`. */
 	async #latest(db) {
 		const row = await latestVaultEntry(db, [CHECKPOINT]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "coffre's vault: keys, grants and members, in the database the app uses, as a Cloudflare Worker or on Node.",
   "license": "MIT",
   "repository": {
@@ -36,15 +36,16 @@
   },
   "dependencies": {
     "drizzle-orm": "0.45.2",
-    "@coffre/core": "0.1.2",
-    "@coffre/db": "0.1.2"
+    "@coffre/core": "0.1.4",
+    "@coffre/db": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "26.1.1",
     "@types/pg": "8.20.0",
     "pg": "8.16.3",
     "tsdown": "0.23.0",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "wrangler": "4.118.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/cloudflare.ts

@@ -8,7 +8,7 @@
  *
  *   export default vault((env: Env) => ({
  *     database: postgres(env.HYPERDRIVE),
- *     kek: { id: 'kek-1', key: env.KEK }, // or awsKms({ keyArn, credentials }), with a signingKey
+ *     kek: { id: env.VAULT_KEY_ID, key: env.VAULT_KEY }, // or awsKms({ keyArn, credentials }), with a signingKey
  *     rootAdmins: ['admin@acme.example'],
  *   }));
  *
@@ -42,8 +42,12 @@ export type WorkersVaultConfig = VaultConfig & { database: PostgresDatabase };
 /** Set when the Worker's module runs `vault(…)`, before any call comes in. */
 let configure: ((env: never) => WorkersVaultConfig) | null = null;
 
-/** The configuration, checked and made ready once per `env`, which the isolate keeps. */
-const ready = new WeakMap<object, Promise<{ database: PostgresDatabase; prepared: PreparedVault }>>();
+/**
+ * The configuration, checked and made ready once per `env`, which the
+ * isolate keeps: the ready value itself, never the work of making it, which
+ * would belong to the call that started it (vault.ts, `PreparedVault`).
+ */
+const ready = new WeakMap<object, { database: PostgresDatabase; prepared: PreparedVault }>();
 
 /**
  * What the app's `VAULT` service binding calls. Each call gets a database of
@@ -56,11 +60,12 @@ export class VaultEntrypoint extends WorkerEntrypoint implements Vault {
     if (entry === undefined) {
       if (configure === null) throw new Error('the vault Worker must export default vault(…)');
       const config = configure(env as never);
-      entry = prepareVault(resolveVaultConfig(config)).then((prepared) => ({ database: config.database, prepared }));
+      const prepared = await prepareVault(resolveVaultConfig(config));
+      // Calls that raced here each made one; the first kept serves them all from now on.
+      entry = ready.get(env) ?? { database: config.database, prepared };
       ready.set(env, entry);
-      entry.catch(() => ready.delete(env));
     }
-    const { database, prepared } = await entry;
+    const { database, prepared } = entry;
     return openVault(createDatabase(new HyperdrivePool(database.hyperdrive.connectionString)), prepared);
   }
 

package/src/config.ts

@@ -38,7 +38,7 @@ export type Kek = { id: string; key: string } | KekProvider;
  *
  *   {
  *     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, // required with a key service; derived from a local KEK otherwise
  *   }
@@ -87,19 +87,19 @@ export function derivedSigningKey(kek: Uint8Array): Buffer {
 function kek(entry: Kek): { provider: KekProvider; signingKey: Buffer | null } {
   if (!('wrap' in entry)) {
     const { id, key } = entry;
-    if (!KEK_ID.test(id)) throw new Error(`KEK id "${id}" must be 1-64 letters, digits, dots, dashes or underscores`);
-    const raw = key32(key, `KEK ${id}`);
+    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 KEK provider's name must be 1-32 lowercase letters, digits or dashes; got "${String(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(`KEK ${provider}: keyId and keyVersion must be 1-255 visible ASCII characters`);
+    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(`KEK ${provider}:${keyId} needs wrap() and unwrap()`);
+    throw new Error(`vault key ${provider}:${keyId} needs wrap() and unwrap()`);
   }
   return { provider: entry, signingKey: null };
 }
@@ -110,7 +110,7 @@ export function resolveVaultConfig(config: VaultConfig): ResolvedVaultConfig {
   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 !== undefined) throw new Error(`two KEKs share an id: ${twice}`);
+  if (twice !== undefined) throw new Error(`two vault keys share an id: ${twice}`);
   return {
     keks: new KekRegistry(current, previous),
     rootAdmins: checkRootAdmins(config.rootAdmins),
@@ -136,8 +136,8 @@ function signingKeys(given: string | undefined, keks: { provider: KekProvider; s
   else {
     const { provider, keyId } = keks[0].provider;
     throw new Error(
-      `signingKey is required with the ${provider} KEK ${keyId}: the vault derives its signing key only from a KEK 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 KEK.',
+      `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);

package/src/log.ts

@@ -132,7 +132,7 @@ function forward(
  */
 function withCause(reason: string): string {
   if (!/^written under vault:\S+, a key this verifier does not hold$/.test(reason)) return reason;
-  return `${reason}: either it is forged, or the vault wrote it under another KEK or signing key, which must stay configured: a KEK that was replaced stays in previousKeks`;
+  return `${reason}: either it is forged, or the vault wrote it under another vault key or signing key, which must stay configured: a vault key that was replaced stays in the vault's config, in previousKeks`;
 }
 
 /**

package/src/vault.ts

@@ -75,7 +75,9 @@ export type VaultOptions = {
 /**
  * A vault's configuration made ready to use, once per process, or once per
  * isolate on Workers: its signer, its log key, and how far it has verified
- * the log. Everything else is in the database, so any number of instances
+ * the log. It holds settled values only, never work under way: on Workers,
+ * a call's I/O is that call's, and a call that waited on another's would be
+ * cancelled with it, as hung (isolate.test.ts). Everything else is in the database, so any number of instances
  * share one set of members, one log and one bulk count.
  */
 export type PreparedVault = {
@@ -101,12 +103,10 @@ export type PreparedVault = {
   since: bigint | null;
   /** Why it writes nothing, once settled that it may not. */
   superseded: string | null;
-  /** The settling under way. */
-  settling: Promise<void> | null;
   /** Tampering this process has logged already, so that a forged row is one entry, not one per request. */
   reported: Set<string>;
-  /** Whether its KEKs open what they wrapped, once asked: `#kekMismatch`. */
-  kekCheck: Promise<string | null> | null;
+  /** Whether its KEKs are decided to open what they wrapped, or not: `#kekMismatch`. */
+  kekChecked: boolean;
   /** Why not, once decided that they do not. */
   wrongKek: string | null;
 };
@@ -121,8 +121,7 @@ export async function prepareVault(config: ResolvedVaultConfig, options: VaultOp
     reported: new Set(),
     since: null,
     superseded: null,
-    settling: null,
-    kekCheck: null,
+    kekChecked: false,
     wrongKek: null,
   };
 }
@@ -223,7 +222,7 @@ const MESSAGES: Record<RefusalCode, string> = {
   root_admin: 'root admins are set in the vault configuration',
   invalid: 'not something the rules allow',
   log_broken: 'the vault log does not hold from the last checkpoint',
-  wrong_kek: "this vault's KEK does not open the data it holds",
+  wrong_kek: "this vault's key does not open the data it holds",
   tampered: "this member's record failed the vault's integrity check",
 };
 
@@ -485,12 +484,10 @@ class VaultService implements Vault {
    */
   async #settled(): Promise<string | null> {
     const prepared = this.#prepared;
-    if (prepared.since === null && prepared.superseded === null) {
-      prepared.settling ??= this.#settle().finally(() => {
-        prepared.settling = null;
-      });
-      await prepared.settling;
-    }
+    // Each call that finds it unsettled reads for itself, over its own
+    // database; calls that race settle it alike, and a rotation they race
+    // to write goes in once (`#rotate`).
+    if (prepared.since === null && prepared.superseded === null) await this.#settle();
     return prepared.superseded;
   }
 
@@ -531,8 +528,8 @@ class VaultService implements Vault {
       }
       prepared.superseded =
         first === undefined
-          ? `the vault's entries are under ${newest.keyId}, a key this vault does not hold: it was given the wrong KEK or signing key, or a KEK it replaced is missing from previousKeks`
-          : `the log moved on from this vault's key, ${current}, to ${newest.keyId}: a vault given a newer KEK replaced it, and a replaced key writes nothing more`;
+          ? `the vault's entries are under ${newest.keyId}, a key this vault does not hold: it was given the wrong vault key or signing key, or a vault key it replaced is missing from previousKeks in its config`
+          : `the log moved on from this vault's key, ${current}, to ${newest.keyId}: a vault given a newer vault key replaced it, and a replaced key writes nothing more`;
       return;
     }
   }
@@ -581,7 +578,7 @@ class VaultService implements Vault {
     return appendEntries(tx, prepared.logKey, entries, async (locked) => {
       const rotation = await store.latestVaultEntry(locked, [KEY_ROTATE]);
       if (rotation === undefined || prepared.logKeys.some((key) => key.keyId === rotation.keyId)) return;
-      prepared.superseded = `the log moved on to ${rotation.keyId}, a key this vault does not hold: a vault given a newer KEK replaced it, and a replaced key writes nothing more`;
+      prepared.superseded = `the log moved on to ${rotation.keyId}, a key this vault does not hold: a vault given a newer vault key replaced it, and a replaced key writes nothing more`;
       throw new Error(prepared.superseded);
     });
   }
@@ -1310,22 +1307,21 @@ class VaultService implements Vault {
   /**
    * Null when every KEK the vault is given opens what it wrapped; otherwise
    * why not, naming the KEK, never its key. Decided once per process, before
-   * its first key operation or checkpoint. A key service that cannot answer
-   * leaves it undecided: the error is thrown, and the next call asks again.
+   * its first key operation or checkpoint: until then, each call checks for
+   * itself, over its own database, and the first verdict is kept. A key
+   * service that cannot answer leaves it undecided: the error is thrown,
+   * and the next call asks again.
    */
-  #kekMismatch(): Promise<string | null> {
+  async #kekMismatch(): Promise<string | null> {
     const prepared = this.#prepared;
-    if (prepared.kekCheck === null) {
-      const check = this.#checkKeks();
-      prepared.kekCheck = check;
-      check.then(
-        (wrong) => void (prepared.wrongKek = wrong),
-        () => {
-          if (prepared.kekCheck === check) prepared.kekCheck = null;
-        },
-      );
+    if (!prepared.kekChecked) {
+      const wrong = await this.#checkKeks();
+      if (!prepared.kekChecked) {
+        prepared.wrongKek = wrong;
+        prepared.kekChecked = true;
+      }
     }
-    return prepared.kekCheck;
+    return prepared.wrongKek;
   }
 
   /**
@@ -1338,13 +1334,7 @@ class VaultService implements Vault {
     // A vault that may not write cannot record a check either; why it may not is the answer.
     const superseded = await this.#settled();
     if (superseded !== null) return superseded;
-    const checks = new Map<string, WrappedDek>();
-    for (const entry of await store.vaultEntriesOf(this.#db, [KEY_CHECK], -1n, VERIFY_BATCH)) {
-      // A check in the vault's name that the vault did not write proves nothing either way.
-      if (!this.#authentic(entry)) continue;
-      const wrapped = JSON.parse(entry.metadata) as WrappedKey;
-      checks.set(`${wrapped.kekProvider}:${wrapped.kekId}`, unwrappable(wrapped));
-    }
+    const checks = await this.#checkValues(this.#db);
     const budget = this.#prepared.options.keyBudgetMs;
     for (const kek of this.#config.keks.all) {
       const operation = { deadline: Date.now() + budget, signal: AbortSignal.timeout(budget) };
@@ -1359,7 +1349,7 @@ class VaultService implements Vault {
           throw error;
         }
       };
-      const mismatch = `this vault's ${kek.provider} KEK ${kek.keyId} does not open the data it holds: it is not the key that wrapped it`;
+      const mismatch = `the vault key ${kek.keyId}${kek.provider === 'local' ? '' : ` (${kek.provider})`}, kek or previousKeks in the vault's config, is not the one that wrapped these values`;
       const check = checks.get(`${kek.provider}:${kek.keyId}`);
       if (check !== undefined) {
         if (!(await opens(check, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE))) return mismatch;
@@ -1375,16 +1365,31 @@ class VaultService implements Vault {
       }
       if (samples.length > 0 && proof === null) return mismatch;
       const wrapped = await kek.wrap(Buffer.from(KEY_CHECK_VALUE), KEY_CHECK_CONTEXT, operation);
-      // The key it opened, if any, is in the log, as every key the vault opens is.
-      await this.#db.transaction((tx) =>
-        this.#append(tx, [
+      // The key it opened, if any, is in the log, as every key the vault opens is. Another call that
+      // checked at the same time may have recorded one first: under the log's lock, the first stays.
+      await this.#db.transaction(async (tx) => {
+        await lockLogHead(tx);
+        if ((await this.#checkValues(tx)).has(`${kek.provider}:${kek.keyId}`)) return;
+        await this.#append(tx, [
           { actor: VAULT_ACTOR, action: KEY_CHECK, decision: 'allow', metadata: JSON.stringify({ ...serialisable(wrapped), proof }) },
-        ]),
-      );
+        ]);
+      });
     }
     return null;
   }
 
+  /** Each KEK's recorded check value, by `provider:keyId`. */
+  async #checkValues(db: Queryable): Promise<Map<string, WrappedDek>> {
+    const checks = new Map<string, WrappedDek>();
+    for (const entry of await store.vaultEntriesOf(db, [KEY_CHECK], -1n, VERIFY_BATCH)) {
+      // A check in the vault's name that the vault did not write proves nothing either way.
+      if (!this.#authentic(entry)) continue;
+      const wrapped = JSON.parse(entry.metadata) as WrappedKey;
+      checks.set(`${wrapped.kekProvider}:${wrapped.kekId}`, unwrappable(wrapped));
+    }
+    return checks;
+  }
+
   // --- checkpoints and the log --------------------------------------------------
 
   /** The last checkpoint the vault signed, and the entry that holds it: its newest allowed `audit.checkpoint`. */