@coffre/db 0.13.0 → 0.14.1

package/dist/migrations/postgres/meta/_journal.json

@@ -127,6 +127,13 @@
       "when": 1792835445795,
       "tag": "0017_capped_alerts",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1792871149580,
+      "tag": "0018_rotate_app_key",
+      "breakpoints": true
     }
   ]
 }

package/dist/schema-version.js

@@ -134,6 +134,13 @@ const KNOWN_MIGRATIONS = {
 			"when": 1792835445795,
 			"tag": "0017_capped_alerts",
 			"breakpoints": true
+		},
+		{
+			"idx": 18,
+			"version": "7",
+			"when": 1792871149580,
+			"tag": "0018_rotate_app_key",
+			"breakpoints": true
 		}
 	].map((entry) => entry.tag),
 	sqlite: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -79,7 +79,7 @@
     "drizzle-orm": "0.45.2",
     "pg": "8.16.3",
     "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.13.0"
+    "@coffre/core": "0.14.1"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/dialect.ts

@@ -113,24 +113,60 @@ export function isUniqueViolation(error: unknown): boolean {
   return false;
 }
 
-/** The network's codes for a server that is not there, and Postgres's for one that will not take the connection. */
-const UNREACHABLE = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE', '57P01', '57P02', '57P03']);
+/** The network's codes for a server that is not there, and Postgres's for one that will not take the connection, or has none left (53300). */
+const UNREACHABLE = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE', '53300', '57P01', '57P02', '57P03']);
+
+/** Hyperdrive's words for having no connection to give, beside pg's and Workers' for one lost. */
+const UNREACHABLE_WORDS = /connection terminated|network connection lost|connect(ion)? timeout|open slot in the pool|acquire a connection from the pool|server connection attempt failed/i;
 
 /**
  * Whether a query failed because the database could not be reached or
  * dropped the connection: an outage, not an answer. Postgres's connection
- * exceptions are class 08; pg and Workers' sockets say so in words.
+ * exceptions are class 08; pg and Workers' sockets say so in words, and so
+ * does Hyperdrive when it has no connection to the database to give: every
+ * one of its pool busy for 15 s ("Timed out while waiting for an open slot
+ * in the pool", FATAL 58000; "Failed to acquire a connection from the
+ * pool"), or none to be made ("Server connection attempt failed:
+ * destination_unavailable").
  */
 export function isUnreachable(error: unknown): boolean {
   for (let cause = error; typeof cause === 'object' && cause !== null; ) {
     const { code, message } = cause as { code?: unknown; message?: unknown };
-    if (typeof code === 'string' && (UNREACHABLE.has(code) || /^08[0-9A-Z]{3}$/.test(code))) return true;
-    if (typeof message === 'string' && /connection terminated|network connection lost|connect(ion)? timeout/i.test(message)) return true;
+    // Class 08 but its protocol violation (08P01), which is the client's bug: asked again, it fails again.
+    if (typeof code === 'string' && (UNREACHABLE.has(code) || (/^08[0-9A-Z]{3}$/.test(code) && code !== '08P01'))) return true;
+    // The words only of what said no code, or Hyperdrive's 58000, and never a message quoting a query and its
+    // parameters (Drizzle's, the Node vault's carrying it): the driver's words are its cause's.
+    if (typeof message === 'string' && (typeof code !== 'string' || code === '58000') && !message.includes('Failed query: ') && UNREACHABLE_WORDS.test(message)) return true;
     cause = (cause as { cause?: unknown }).cause;
   }
   return false;
 }
 
+/** Postgres's codes for a statement that gave up waiting: on a lock (55P03), or past its own bound (57014). */
+const GAVE_UP = new Set(['55P03', '57014']);
+
+/**
+ * Whether a statement gave up waiting, on a lock or past its bound: the
+ * database too busy to answer in time, or a transaction held too long,
+ * which a bug may be (one held across a vault call waits on the vault's
+ * decision, which waits on it).
+ */
+export function gaveUp(error: unknown): boolean {
+  for (let cause = error; typeof cause === 'object' && cause !== null; cause = (cause as { cause?: unknown }).cause) {
+    if (GAVE_UP.has((cause as { code?: unknown }).code as string)) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether a query failed for want of the database, not for anything the
+ * request asked: it could not be reached (`isUnreachable`), or a statement
+ * gave up waiting (`gaveUp`). The same request may well succeed in a moment.
+ */
+export function isUnavailable(error: unknown): boolean {
+  return isUnreachable(error) || gaveUp(error);
+}
+
 /**
  * A consistent read of several statements that cannot write, such as
  * verifying the chain. SQLite ignores it: its transactions already see one

package/src/log.ts

@@ -15,7 +15,8 @@ import { clockMillis, engineOf, forUpdate } from './dialect.ts';
  * from any process take their numbers in one order. It then reads the
  * database clock, after the lock, and the log's last entry, which the head
  * must name: a head that does not was moved, or entries were deleted behind
- * it, and the append refuses.
+ * it, and the append refuses. The same statement says whether the log has
+ * moved on from the key it appends under (`KeyRetired`).
  *
  * This is deliberately not a queue and not best-effort: the entries go in
  * the caller's transaction, so if the append fails, what it records does
@@ -70,6 +71,26 @@ export class LogRewound extends Error {
   }
 }
 
+/**
+ * An append under a key the log has moved on from: an entry of its
+ * author's, `key.reseal` or `key.rotate`, names it as the key it moves
+ * from (`MOVES_FROM`), and a key moved from writes no more.
+ */
+export class KeyRetired extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KeyRetired';
+  }
+}
+
+/**
+ * The actions by which an author moves to a new key, each under the new one
+ * and naming the key it moves from as its subject: from the first, that key
+ * writes no more (`KeyRetired`). The app's key rotation writes them
+ * (packages/server/src/key-rotation.ts).
+ */
+export const MOVES_FROM = ['key.reseal', 'key.rotate'] as const;
+
 /**
  * The newest head each writer has written, under each of its keys, while
  * the process lives. A head is remembered only once the transaction that
@@ -94,6 +115,15 @@ export function forgetLogHeads(): void {
   epoch += 1;
 }
 
+/**
+ * The transactions that hold the head: an append in one reads what it
+ * needs under the lock in one statement, where one that does not first
+ * takes the lock in another. A savepoint's transaction is another to this
+ * set, so a lock is marked on the object that took it, and an append made
+ * through another object locks again, which is free.
+ */
+const holding = new WeakSet<Transaction>();
+
 /**
  * Lock the log's head, and read it. A transaction that appends takes this
  * before any other row, so the lock order is the same everywhere; taking it
@@ -102,9 +132,29 @@ export function forgetLogHeads(): void {
 export async function lockLogHead(tx: Transaction): Promise<{ nextSeq: bigint; headHash: Buffer }> {
   const [head] = await lockedHead(tx);
   if (head === undefined) throw new Error('audit_chain_head is missing; refusing to write an unchained entry');
+  holding.add(tx);
   return head;
 }
 
+/**
+ * Lock the log's head if no one holds it, without waiting: whether it is
+ * held now. For work any caller may do, of which one at a time is enough,
+ * which a request that finds the head taken leaves to the one that has it.
+ * SQLite's transactions hold the whole file, so the head is always free.
+ */
+export async function lockLogHeadIfFree(tx: Transaction): Promise<boolean> {
+  if (engineOf(tx) === 'sqlite') {
+    const held = (await lockedHead(tx)).length > 0;
+    if (held) holding.add(tx);
+    return held;
+  }
+  const { rows } = await (tx as unknown as { execute(query: SQL): Promise<{ rows: unknown[] }> }).execute(
+    sql`SELECT next_seq FROM audit_chain_head WHERE only_row FOR UPDATE SKIP LOCKED`,
+  );
+  if (rows.length > 0) holding.add(tx);
+  return rows.length > 0;
+}
+
 const lockedHead = prepared((db) => {
   const { auditChainHead } = tablesOf(db);
   return forUpdate(
@@ -135,10 +185,11 @@ export async function appendEntries(
   const { auditChainHead, auditLog } = tablesOf(tx);
 
   // Every append queues here, if its transaction has not already.
-  const head = locked?.head ?? (await lockLogHead(tx));
+  if (locked === undefined && !holding.has(tx)) await lockLogHead(tx);
   await check?.(tx);
-  const now = locked?.at ?? (await clockNow(tx))[0]!.now;
-  const last = locked === undefined ? (await lastEntry(tx))[0] : locked.last ?? undefined;
+  const held = locked ?? (await readUnderHead(tx, key));
+  const { head, at: now } = held;
+  const last = held.last ?? undefined;
 
   const expected = last === undefined ? { nextSeq: 0n, headHash: GENESIS_HASH } : { nextSeq: last.seq + 1n, headHash: last.hash };
   if (head.nextSeq !== expected.nextSeq || !head.headHash.equals(expected.headHash)) {
@@ -201,14 +252,52 @@ export async function appendEntries(
 /** A head locked by a statement of the caller's, and what it read under the lock (`appendEntries`). */
 export type HeldHead = { head: { nextSeq: bigint; headHash: Buffer }; last: { seq: bigint; hash: Buffer } | null; at: number };
 
+/**
+ * What an append reads under the head its transaction holds, in one
+ * statement: the head, the clock and the log's last entry, all as of the
+ * lock, since locking a head the transaction holds waits for nothing, and
+ * after the append's `check`. The log's own last row says whether the log
+ * has moved on from `key`.
+ */
+async function readUnderHead(tx: Transaction, key: LogKey): Promise<HeldHead> {
+  const [read] = await underHead(tx, { author: key.author, keyId: key.keyId });
+  if (read === undefined) throw new Error('audit_chain_head is missing; refusing to write an unchained entry');
+  if (read.retired) throw new KeyRetired(`the log moved on from ${key.keyId}: a key the ${key.author} rotated from writes no more`);
+  return {
+    head: { nextSeq: read.nextSeq, headHash: read.headHash },
+    last: read.lastSeq === null || read.lastHash === null ? null : { seq: read.lastSeq, hash: read.lastHash },
+    at: read.now,
+  };
+}
+
 /** Entries one statement inserts at most, at 21 parameters each: Postgres takes 65,535. */
 const ROWS_AT_ONCE = 3000;
 
-const clockNow = prepared((db) => db.select({ now: clockMillis(db) }).from(tablesOf(db).auditChainHead));
-
-const lastEntry = prepared((db) => {
-  const { auditLog } = tablesOf(db);
-  return db.select({ seq: auditLog.seq, hash: auditLog.hash }).from(auditLog).orderBy(desc(auditLog.seq)).limit(1);
+/**
+ * `readUnderHead`'s statement. Its `FOR UPDATE` waits for nothing in a
+ * transaction that holds the head, and stays for one that would not: there
+ * it waits, and if an append committed meanwhile, its head, read again
+ * after the wait, disagrees with the last entry its snapshot saw before it,
+ * so the append refuses (`LogHeadMismatch`) rather than writing unlocked.
+ */
+const underHead = prepared((db) => {
+  const { auditChainHead, auditLog } = tablesOf(db);
+  const moved = sql.raw(MOVES_FROM.map((action) => `'${action}'`).join(', '));
+  const newest = (column: SQL) => sql`(SELECT ${column} FROM audit_log ORDER BY seq DESC LIMIT 1)`;
+  return forUpdate(
+    db,
+    db
+      .select({
+        nextSeq: auditChainHead.nextSeq,
+        headHash: auditChainHead.headHash,
+        now: clockMillis(db),
+        lastSeq: newest(sql`seq`).mapWith(auditLog.seq) as SQL<bigint | null>,
+        lastHash: newest(sql`hash`).mapWith(auditLog.hash) as SQL<Buffer | null>,
+        retired: sql<boolean | number>`EXISTS (SELECT 1 FROM audit_log moved WHERE moved.author = ${sql.placeholder('author')} AND moved.subject_principal = ${sql.placeholder('keyId')} AND moved.action IN (${moved}))`,
+      })
+      .from(auditChainHead)
+      .where(eq(auditChainHead.onlyRow, true)),
+  );
 });
 
 // --- reading the vault's entries back ---------------------------------------------

package/src/migrations/postgres/0018_rotate_app_key.sql

@@ -0,0 +1,2 @@
+-- The app key's rotation (T105) signs every enrollment code again under the new key, as it does every other signed row. It only adds a grant: the release before writes no enrollment's MAC but at its insert.
+GRANT UPDATE (auth_mac) ON enrollments TO coffre_app;