@coffre/vault 0.14.2 → 0.14.3

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-zkW6DEm9.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-CIq4i_KT.js";
 import { AdmitInput, ChangePolicyInput, EndReferencesInput, ReferenceInput, RemoveInput, RewrapInput, SetAccessInput, SetSettingsInput, 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,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-B0d-W-SI.js";
-import { n as prepareVault, t as openVault } from "./vault-hLffpMy5.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-NM5NsYFs.js";
+import { n as prepareVault, t as openVault } from "./vault-B4IivgU8.js";
 import { createDatabase } from "@coffre/db";
 import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";

package/dist/{index-zkW6DEm9.d.ts → index-CIq4i_KT.d.ts}

@@ -1,5 +1,5 @@
 import { checkpointMessage as checkpointMessage$1, verifyCheckpoint } from "@coffre/core/vault";
-import { AwsCredentials, AwsKmsOptions, KekBadClaimError as KekBadClaimError$1, KekProvider, KekProvider as KekProvider$1, KekRegistry, KekUnavailableError as KekUnavailableError$1, WrappedDek, awsKms } from "@coffre/core/kek";
+import { AwsCredentials, AwsKmsOptions, KekBadClaimError as KekBadClaimError$1, KekProvider, KekProvider as KekProvider$1, KekRegistry, KekUnavailableError as KekUnavailableError$1, WrappedDek, awsKms, derivedSigningKey } from "@coffre/core/kek";
 import { SecretContext } from "@coffre/core/envelope";
 //#region src/config.d.ts
 /**
@@ -72,7 +72,5 @@ type Owners = {
   owners?: never;
   bootstrapOwners?: never;
 };
-/** 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, derivedSigningKey as p, KekBadClaimError$1 as r, WrappedDek as s, AwsCredentials as t, verifyCheckpoint 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, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-zkW6DEm9.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-CIq4i_KT.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-B0d-W-SI.js";
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, t as KekBadClaimError } from "./src-NM5NsYFs.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-zkW6DEm9.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-CIq4i_KT.js";
 import { Vault, Vault as Vault$1 } from "@coffre/core/vault";
 import { Database } from "@coffre/db";
 import "@coffre/core/access";

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-B0d-W-SI.js";
-import { n as prepareVault, t as openVault } from "./vault-hLffpMy5.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-NM5NsYFs.js";
+import { n as prepareVault, t as openVault } from "./vault-B4IivgU8.js";
 import { isUnavailable } from "@coffre/db/dialect";
 import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
 import { Agent, createServer, request } from "node:http";

package/dist/{src-B0d-W-SI.js → src-NM5NsYFs.js}

@@ -1,6 +1,5 @@
 import { checkpointMessage as checkpointMessage$1, verifyCheckpoint } 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";
+import { KekBadClaimError as KekBadClaimError$1, KekRegistry, KekUnavailableError as KekUnavailableError$1, LocalKekProvider, awsKms, derivedSigningKey } from "@coffre/core/kek";
 //#region src/config.ts
 /**
 * 1000 different keys in 15 minutes, which no person or deploy pipeline
@@ -21,12 +20,6 @@ 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)) {

package/dist/{vault-hLffpMy5.js → vault-B4IivgU8.js}

@@ -1,7 +1,7 @@
 import { ACCESS_ACTIONS, ACCESS_ACTIONS as ACCESS_ACTIONS$1, POLICY_REVISION, accessRevision, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision } from "@coffre/core/vault";
 import { DEK_BYTES, KEY_CHECK, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE, KekBadClaimError, KekCancelledError, KekUnavailableError, LocalKekProvider } from "@coffre/core/kek";
-import { createHash, createHmac, hkdfSync, randomUUID, timingSafeEqual } from "node:crypto";
 import { prepared, tablesOf } from "@coffre/db";
+import { createHash, createHmac, hkdfSync, randomUUID, timingSafeEqual } from "node:crypto";
 import { DEFAULT_POLICY, EVERYWHERE, EVERY_ENVIRONMENT, FIXED_ROLES, INSTANCE_ROLES, NOTHING, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_ID, UNWRITTEN_FORK_MS, allows, assignableToEnvironment, definitionProblem, givesService, grantKind, isBuiltinRole, isCredentialScope, isInstanceRole, isRole, isScope, managesService, mayManageAccess, normalDefinition, normalScope, ownsInstance, ownsProject, readsSensitive, runsInstance, setsUpServices, unscoped, useOnly, withinCredential } from "@coffre/core/access";
 import { GENESIS_HASH, deriveLogKey, verifyEntries } from "@coffre/core/audit";
 import { checkContext, ownerKey } from "@coffre/core/envelope";
@@ -178,10 +178,16 @@ function referenceRefusal(reader, holder, source, environments, nature) {
 //#region src/store.ts
 /**
 * On Postgres, fail a lock wait in this transaction after `ms`, rather than
-* wait for ever behind a transaction that never ends.
+* wait for ever behind a transaction that never ends; with `statements`,
+* any statement that takes longer, too. A queue for a row each holder
+* updates, as the log's head, is no one wait: a waiter follows each update
+* to the row's new version and waits again, its lock's clock started over,
+* so only the statement's own bound ends it.
 */
-async function boundLockWaits(tx, ms) {
-	if (engineOf(tx) === "postgres") await tx.execute(sql.raw(`SET LOCAL lock_timeout = ${Math.trunc(ms)}`));
+async function boundLockWaits(tx, ms, statements = false) {
+	if (engineOf(tx) !== "postgres") return;
+	const bound = String(Math.trunc(ms));
+	await tx.execute(statements ? sql`SELECT set_config('lock_timeout', ${bound}, true), set_config('statement_timeout', ${bound}, true)` : sql.raw(`SET LOCAL lock_timeout = ${bound}`));
 }
 /** The database's clock, now. */
 async function now(db) {
@@ -251,14 +257,37 @@ async function instanceOwners(db) {
 * Lock these members' rows for the rest of the transaction, in one order
 * everywhere, and read them: those that have none are not in the map. Every
 * decision about a member takes its row first, so two of them, from any
-* process, never interleave.
+* process, never interleave; but `shared`, for a decision that writes no
+* member's row, as a read, takes them as other such decisions do, side by
+* side, and only what changes the member waits for it, and it for that.
+*
+* Postgres lets a share lock join those already held even while a writer
+* waits for them, so a steady stream of one member's reads would hold a
+* removal off for ever. So each row comes with an advisory lock on its
+* principal, which the lock manager queues in order: a read asked after a
+* writer waits behind it. The same statement takes it, then the row, one
+* principal after another.
 */
-async function lockMembers(tx, principals) {
+async function lockMembers(tx, principals, shared = false) {
 	const { vaultMembers } = tablesOf(tx);
-	const rows = await forUpdate(tx, tx.select(memberColumns(tx)).from(vaultMembers).where(inArray(vaultMembers.principal, [...new Set(principals)])).orderBy(asc(vaultMembers.principal)), "no key update");
-	return new Map(rows.map((row) => [row.principal, memberOf$1(row)]));
+	const queued = engineOf(tx) === "postgres" ? { queued: sql`${sql.raw(shared ? "pg_advisory_xact_lock_shared" : "pg_advisory_xact_lock")}(${MEMBER_QUEUE}, hashtext(${vaultMembers.principal}))` } : {};
+	const rows = await forUpdate(tx, tx.select({
+		...memberColumns(tx),
+		...queued
+	}).from(vaultMembers).where(inArray(vaultMembers.principal, [...new Set(principals)])).orderBy(asc(vaultMembers.principal)), shared ? "share" : "no key update");
+	return new Map(rows.map(({ queued: _, ...row }) => [row.principal, memberOf$1(row)]));
 }
 /**
+* The first key of the members' queues, Postgres's advisory locks: the
+* second is the principal's hash, and the pair is in a space of its own,
+* apart from the migrator's single key. A hash two principals share queues
+* one behind the other's writer; and two changes that each lock two
+* members, where one's first and the other's second share it, can wait on
+* each other, which Postgres ends after a second by failing one of them
+* (40P01): about n² / 2³³ for an instance of n members.
+*/
+const MEMBER_QUEUE = 1668245101;
+/**
 * Add `row`. A principal has one row: when two decisions admit the same
 * one at once, the second fails here, and rolls back with its entries.
 */
@@ -1782,6 +1811,14 @@ function openVault(db, prepared) {
 const KEY_BUDGET_MS = 5e3;
 /** How long a decision waits for a lock: above the key budget, so a removal outwaits a read in flight. */
 const LOCK_TIMEOUT_MS = 15e3;
+/**
+* How long a statement of a read's decision runs, a wait for a lock
+* included: a read waits only for what changes its reader, and for the
+* log's head. Longer is a queue, which holds the read's connection while it
+* waits; refused, it fails as unavailable at once, and its caller tries
+* again later.
+*/
+const READ_LOCK_TIMEOUT_MS = 3e3;
 /** A member: `user:<email>` or `token:<name>`. */
 const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
 /** A person, and a service account: only a person sets one up (`givesService`). */
@@ -1986,30 +2023,32 @@ var VaultService = class {
 	* commits: no decision acts on a policy read before it. A key operation
 	* alone takes the head later (`late`), once its key service has answered,
 	* which it must not wait on holding it, and decides again then (`#keys`).
+	* A read (`reads`) changes no member: it takes their rows shared, so
+	* that one member's reads decide side by side (`lockMembers`).
 	*/
-	async #decide(principals, decide, late = false, asked = {}) {
+	async #decide(principals, decide, how = {}) {
 		const superseded = await this.#settled();
 		if (superseded !== null) return {
 			ok: false,
 			refusal: refusal("wrong_kek", superseded)
 		};
-		return this.#decideNow(principals, decide, late, asked);
+		return this.#decideNow(principals, decide, how);
 	}
 	/** `#decide`, once the vault is settled. */
-	async #decideNow(principals, decide, late = false, asked = {}) {
+	async #decideNow(principals, decide, how = {}) {
 		const reports = [];
 		for (let attempt = 1;; attempt += 1) try {
-			return await this.#decideOnce(principals, decide, reports, late, asked);
+			return await this.#decideOnce(principals, decide, reports, how);
 		} catch (error) {
 			if (attempt < 3 && (error instanceof Retry || isUniqueViolation(error))) continue;
 			throw error;
 		}
 	}
-	async #decideOnce(principals, decide, reports, late, asked) {
+	async #decideOnce(principals, decide, reports, { late = false, asked = {}, reads: shared = false }) {
 		try {
 			const result = await this.#db.transaction(async (tx) => {
-				await boundLockWaits(tx, LOCK_TIMEOUT_MS);
-				const members = principals.length === 0 ? /* @__PURE__ */ new Map() : await lockMembers(tx, principals);
+				await boundLockWaits(tx, shared ? READ_LOCK_TIMEOUT_MS : LOCK_TIMEOUT_MS, shared);
+				const members = principals.length === 0 ? /* @__PURE__ */ new Map() : await lockMembers(tx, principals, shared);
 				const reads = await this.#snapshot(tx, principals, asked, !late);
 				const d = {
 					tx,
@@ -2039,7 +2078,9 @@ var VaultService = class {
 					for (const then of d.after) then((entry) => seqs.get(entry));
 				}
 				for (const write of d.writes) await write(at);
-				for (const principal of /* @__PURE__ */ new Set([...d.touched, ...accessSeq.keys()])) await this.#seal(d, principal, accessSeq.get(principal));
+				const sealing = /* @__PURE__ */ new Set([...d.touched, ...accessSeq.keys()]);
+				if (shared && sealing.size > 0) throw new Error("a read changes no member, and seals no row");
+				for (const principal of sealing) await this.#seal(d, principal, accessSeq.get(principal));
 				return result;
 			});
 			this.#reported(reports);
@@ -2615,7 +2656,7 @@ var VaultService = class {
 				if (this.#revisionOf(standing, d) !== asked) throw new Refused(refusal("access_changed", MESSAGES.access_changed), []);
 			}
 			throw new Refused(refusal(code, message), entries);
-		});
+		}, { reads: true });
 	}
 	/**
 	* The data key, or null when it does not open as this secret's: a claim
@@ -2733,7 +2774,10 @@ var VaultService = class {
 						}))
 					})
 				}], [], d.reads)).seqStart };
-			}, false, reads);
+			}, {
+				asked: reads,
+				reads: true
+			});
 			if (!intent.ok) return intent;
 			intentSeq = intent.seq;
 		}
@@ -2779,13 +2823,19 @@ var VaultService = class {
 			} finally {
 				for (const value of done) value.wipe();
 			}
-		}, late, reads);
+		}, {
+			late,
+			asked: reads,
+			reads: true
+		});
 	}
 	/**
 	* Whether this read's keys would take the reader past the bulk limit: the
 	* distinct keys released to them in the window, these among them. A key
 	* read again exposes nothing new, so it counts once, whatever its version.
-	* Counted under their row's lock, so exactly (`Reads`).
+	* Counted under the log's head, which every release appends under, so
+	* exactly: one reader's reads decide side by side under their row, and
+	* each counts the others' releases again once it holds the head (`#keys`).
 	*/
 	#overBulkLimit(d) {
 		return d.reads.released > this.#config.bulkLimit.count;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "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,8 +36,8 @@
   },
   "dependencies": {
     "drizzle-orm": "0.45.2",
-    "@coffre/core": "0.14.2",
-    "@coffre/db": "0.14.2"
+    "@coffre/core": "0.14.3",
+    "@coffre/db": "0.14.3"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/config.ts

@@ -1,6 +1,4 @@
-import { hkdfSync } from 'node:crypto';
-
-import { KekRegistry, LocalKekProvider, type KekProvider } from '@coffre/core/kek';
+import { derivedSigningKey, KekRegistry, LocalKekProvider, type KekProvider } from '@coffre/core/kek';
 
 /** At most `count` distinct data keys unwrapped per principal in any `windowMs`. */
 export type BulkLimit = { count: number; windowMs: number };
@@ -108,13 +106,7 @@ 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. */
-export function derivedSigningKey(kek: Uint8Array): Buffer {
-  return Buffer.from(hkdfSync('sha256', kek, new Uint8Array(0), SIGNING_KEY_LABEL, 32));
-}
+export { derivedSigningKey };
 
 /** A KEK as the registry takes it, and the signing key it stands for when it is one the vault holds. */
 function kek(entry: Kek): { provider: KekProvider; signingKey: Buffer | null } {

package/src/store.ts

@@ -53,10 +53,18 @@ export { newestVaultEntries } from '@coffre/db/log';
 
 /**
  * On Postgres, fail a lock wait in this transaction after `ms`, rather than
- * wait for ever behind a transaction that never ends.
+ * wait for ever behind a transaction that never ends; with `statements`,
+ * any statement that takes longer, too. A queue for a row each holder
+ * updates, as the log's head, is no one wait: a waiter follows each update
+ * to the row's new version and waits again, its lock's clock started over,
+ * so only the statement's own bound ends it.
  */
-export async function boundLockWaits(tx: Transaction, ms: number): Promise<void> {
-  if (engineOf(tx) === 'postgres') await tx.execute(sql.raw(`SET LOCAL lock_timeout = ${Math.trunc(ms)}`));
+export async function boundLockWaits(tx: Transaction, ms: number, statements = false): Promise<void> {
+  if (engineOf(tx) !== 'postgres') return;
+  const bound = String(Math.trunc(ms));
+  await tx.execute(statements
+    ? sql`SELECT set_config('lock_timeout', ${bound}, true), set_config('statement_timeout', ${bound}, true)`
+    : sql.raw(`SET LOCAL lock_timeout = ${bound}`));
 }
 
 /** The database's clock, now. */
@@ -136,22 +144,45 @@ export async function instanceOwners(db: Queryable): Promise<Member[]> {
  * Lock these members' rows for the rest of the transaction, in one order
  * everywhere, and read them: those that have none are not in the map. Every
  * decision about a member takes its row first, so two of them, from any
- * process, never interleave.
+ * process, never interleave; but `shared`, for a decision that writes no
+ * member's row, as a read, takes them as other such decisions do, side by
+ * side, and only what changes the member waits for it, and it for that.
+ *
+ * Postgres lets a share lock join those already held even while a writer
+ * waits for them, so a steady stream of one member's reads would hold a
+ * removal off for ever. So each row comes with an advisory lock on its
+ * principal, which the lock manager queues in order: a read asked after a
+ * writer waits behind it. The same statement takes it, then the row, one
+ * principal after another.
  */
-export async function lockMembers(tx: Transaction, principals: readonly string[]): Promise<Map<string, Member>> {
+export async function lockMembers(tx: Transaction, principals: readonly string[], shared = false): Promise<Map<string, Member>> {
   const { vaultMembers } = tablesOf(tx);
+  const queued: Record<string, SQL> = engineOf(tx) === 'postgres'
+    ? { queued: sql`${sql.raw(shared ? 'pg_advisory_xact_lock_shared' : 'pg_advisory_xact_lock')}(${MEMBER_QUEUE}, hashtext(${vaultMembers.principal}))` }
+    : {};
   const rows = await forUpdate(
     tx,
     tx
-      .select(memberColumns(tx))
+      .select({ ...memberColumns(tx), ...queued })
       .from(vaultMembers)
       .where(inArray(vaultMembers.principal, [...new Set(principals)]))
       .orderBy(asc(vaultMembers.principal)),
-    'no key update',
+    shared ? 'share' : 'no key update',
   );
-  return new Map((rows as StoredMember[]).map((row) => [row.principal, memberOf(row)]));
+  return new Map((rows as (StoredMember & { queued?: unknown })[]).map(({ queued: _, ...row }) => [row.principal, memberOf(row)]));
 }
 
+/**
+ * The first key of the members' queues, Postgres's advisory locks: the
+ * second is the principal's hash, and the pair is in a space of its own,
+ * apart from the migrator's single key. A hash two principals share queues
+ * one behind the other's writer; and two changes that each lock two
+ * members, where one's first and the other's second share it, can wait on
+ * each other, which Postgres ends after a second by failing one of them
+ * (40P01): about n² / 2³³ for an instance of n members.
+ */
+const MEMBER_QUEUE = 0x636f666d;
+
 /**
  * Add `row`. A principal has one row: when two decisions admit the same
  * one at once, the second fails here, and rolls back with its entries.

package/src/vault.ts

@@ -203,6 +203,15 @@ const KEY_BUDGET_MS = 5_000;
 /** How long a decision waits for a lock: above the key budget, so a removal outwaits a read in flight. */
 const LOCK_TIMEOUT_MS = 15_000;
 
+/**
+ * How long a statement of a read's decision runs, a wait for a lock
+ * included: a read waits only for what changes its reader, and for the
+ * log's head. Longer is a queue, which holds the read's connection while it
+ * waits; refused, it fails as unavailable at once, and its caller tries
+ * again later.
+ */
+const READ_LOCK_TIMEOUT_MS = 3_000;
+
 /** A member: `user:<email>` or `token:<name>`. */
 const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
 
@@ -392,6 +401,13 @@ type Decision = {
  */
 type Reads = Pick<Asked, 'environments' | 'references'> & { released?: { principal: string; keys: readonly string[] } };
 
+/**
+ * How a decision runs: `late` takes the log's head only to append, `asked`
+ * is what it reads besides its members, and `reads` says it changes none
+ * of them (`#decide`).
+ */
+type How = { late?: boolean; asked?: Reads; reads?: boolean };
+
 /** The actions of the entries the vault writes about keys. */
 type KeyAction = 'secret.read' | 'key.wrap' | 'key.rewrap';
 
@@ -497,19 +513,21 @@ class VaultService implements Vault {
    * commits: no decision acts on a policy read before it. A key operation
    * alone takes the head later (`late`), once its key service has answered,
    * which it must not wait on holding it, and decides again then (`#keys`).
+   * A read (`reads`) changes no member: it takes their rows shared, so
+   * that one member's reads decide side by side (`lockMembers`).
    */
-  async #decide<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, late = false, asked: Reads = {}): Promise<Outcome<T>> {
+  async #decide<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, how: How = {}): Promise<Outcome<T>> {
     const superseded = await this.#settled();
     if (superseded !== null) return { ok: false, refusal: refusal('wrong_kek', superseded) };
-    return this.#decideNow(principals, decide, late, asked);
+    return this.#decideNow(principals, decide, how);
   }
 
   /** `#decide`, once the vault is settled. */
-  async #decideNow<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, late = false, asked: Reads = {}): Promise<Outcome<T>> {
+  async #decideNow<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, how: How = {}): Promise<Outcome<T>> {
     const reports: NewEntry[] = [];
     for (let attempt = 1; ; attempt += 1) {
       try {
-        return await this.#decideOnce(principals, decide, reports, late, asked);
+        return await this.#decideOnce(principals, decide, reports, how);
       } catch (error) {
         // A member who had no row when this decision locked theirs, and has
         // one now: another decision admitted them meanwhile. Again, with it.
@@ -519,11 +537,11 @@ class VaultService implements Vault {
     }
   }
 
-  async #decideOnce<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, reports: NewEntry[], late: boolean, asked: Reads): Promise<Outcome<T>> {
+  async #decideOnce<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, reports: NewEntry[], { late = false, asked = {}, reads: shared = false }: How): Promise<Outcome<T>> {
     try {
       const result = await this.#db.transaction(async (tx) => {
-        await store.boundLockWaits(tx, LOCK_TIMEOUT_MS);
-        const members = principals.length === 0 ? new Map<string, Member>() : await store.lockMembers(tx, principals);
+        await store.boundLockWaits(tx, shared ? READ_LOCK_TIMEOUT_MS : LOCK_TIMEOUT_MS, shared);
+        const members = principals.length === 0 ? new Map<string, Member>() : await store.lockMembers(tx, principals, shared);
         // Then the head, and everything the decision reads, in one statement (`snapshot` says why it holds).
         const reads = await this.#snapshot(tx, principals, asked, !late);
         const d: Decision = {
@@ -547,9 +565,10 @@ class VaultService implements Vault {
           for (const then of d.after) then((entry) => seqs.get(entry)!);
         }
         for (const write of d.writes) await write(at);
-        for (const principal of new Set([...d.touched, ...accessSeq.keys()])) {
-          await this.#seal(d, principal, accessSeq.get(principal));
-        }
+        const sealing = new Set([...d.touched, ...accessSeq.keys()]);
+        // Under a share lock, a write to the row would wait for every other read holding it, and they for it.
+        if (shared && sealing.size > 0) throw new Error('a read changes no member, and seals no row');
+        for (const principal of sealing) await this.#seal(d, principal, accessSeq.get(principal));
         return result;
       });
       this.#reported(reports);
@@ -558,6 +577,7 @@ class VaultService implements Vault {
       if (!(error instanceof Refused || error instanceof Outage)) throw error;
       const entries = [...reports, ...readsByPlace(error.entries)];
       if (entries.length > 0) {
+        // A refusal's entries are written whatever the decision's bound: it answers only once they are.
         await this.#db.transaction(async (tx) => {
           await store.boundLockWaits(tx, LOCK_TIMEOUT_MS);
           await this.#append(tx, entries);
@@ -1148,7 +1168,7 @@ class VaultService implements Vault {
         if (this.#revisionOf(standing, d) !== asked) throw new Refused(refusal('access_changed', MESSAGES.access_changed), []);
       }
       throw new Refused(refusal(code, message), entries);
-    });
+    }, { reads: true });
   }
 
   /**
@@ -1299,12 +1319,13 @@ class VaultService implements Vault {
           }),
         }], [], d.reads);
         return { seq: appended.seqStart };
-      }, false, reads);
+      }, { asked: reads, reads: true });
       if (!intent.ok) return intent;
       intentSeq = intent.seq;
     }
 
-    // Under the reader's row: the check, the key operations, and their outcome. With a key in memory, under the
+    // Under the reader's row, which their other reads share and a change to them waits for: the check, the key
+    // operations, and their outcome. With a key in memory, under the
     // log's head too, from the start (`#decideOnce`): what the check read stands until the commit, as every change it
     // reads appends under the head, and the head waits on nothing slow. With a key service, which nothing may wait on
     // holding the head, the head is taken once the keys are open, and what the check read is read again under it.
@@ -1377,14 +1398,16 @@ class VaultService implements Vault {
       } finally {
         for (const value of done) value.wipe();
       }
-    }, late, reads);
+    }, { late, asked: reads, reads: true });
   }
 
   /**
    * Whether this read's keys would take the reader past the bulk limit: the
    * distinct keys released to them in the window, these among them. A key
    * read again exposes nothing new, so it counts once, whatever its version.
-   * Counted under their row's lock, so exactly (`Reads`).
+   * Counted under the log's head, which every release appends under, so
+   * exactly: one reader's reads decide side by side under their row, and
+   * each counts the others' releases again once it holds the head (`#keys`).
    */
   #overBulkLimit(d: Decision): boolean {
     return d.reads.released > this.#config.bulkLimit.count;